Pipeline Stages summary


Stages per typePurpose
controls
   APPEND      To run a device driver and append records to the end.
   FRTARGET    To select records from a target.
   FROMTARGET  To select records from a target.
   IN          Simulate pipe input stream while using pipe in Java
   OUT         Simulate pipe output stream while using pipe in Java
   PREFACE     To invoke another stage and write its output at first into primary output stream
   PIPEIN      Simulate pipe input stream while using pipe in Java
   PIPEOUT     Simulate pipe output stream while using pipe in Java
   RUNPIPE     To run input records as pipeline commands.
   RUNFILE     To read a file as a pipeline command and execute it.
   SUB ADDPIPE  To simulate and practice the addpipe command.
   SUB CALLPIPE To simulate and practice the callpipe command.
drivers
   files
      <bin        To read content of a binary file.(buffer of 1024)
      <           To read content of a file.
      >>bin       To append data to a binary file
      >>          To append data to a file.
      >bin        To write data to a binary file.
      >           To write data to a file.
      GETFILES    To read a list of files into pipeline
   other
      BEAT        To pass records in an specified interval. Act as a heartbeat monitor.
      BLUEPAGES   To select records from BluePages directory...
      CLIPBOARD   To get/set text string from/into system clipboard.
      DB2         To access DB2 databases.
      DELAY       To copy input records to output at a particular time or after interval.
      HOLE        To consume all input streams records.
      JAVAP       (under development)To disassemble Java class file.
      JAVA        (under development)To compile,load,and execute user written stage.
      LITERAL     To append a string to its primary output stream.
      MQSERIES    Sample to browse,get,put data from/into queues
      MSGSEND     (under development)Simple mail sender.
      PING        To ping server.
      RANGE       To generate range of numbers
      REMOTE      (StageClient alias) To execute a stage on a server (remote execution)
      STAGECLIENT To execute a stage on a server (remote execution)
      STAGESERVER To start the server monitor to execute stages from clients
   terminal
      CONSOLE     To display/read records to/from the terminal
      FULLSCREEN  To display records (like CONSOLE) in fullscreen mode.
      IMMCMD      To submit immediate commands
      MENU3270    Sample to display in a 3270 manner
   vars
      STEM        To set/get Arrays to/from a Java class
      VAR         To set/get vars to/from a Java class
filters
   buffer
      INSTORE     To read input records into storage and write their hashcode to output stream.
      OUTSTORE    To read records from storage using their hashcode and write them to output stream. (see INSTORE)
   cutpaste
      CHOP        To cut record at specified target (column, string, character).
      JOINCONT    To join records that are marked with a continuation character.
      JOIN4SPLIT  To concatenate all record and split at the same time (avoid to put all records in one)
      JOIN        To concatenate one or more input records into a single output record.
      SPLIT       To split records at blank, or other character or string.
      STRIP       To remove leading and trailing blanks.
   formatconv
      CALCULATE   To do mathematical calculations.
      LAYOUT      To reformat a report with layout..for spreadsheet import.
      PARCEL      To parcel  its primary input record of the length specified by number read from secondary input stream.
      PARSER      To parse data according to rules defined in argument or in secondary input stream.
   other
      COUNT       To count lines, characters, words in records
      DUPLICATE   To write each input record into the pipeline one more time than the specified number.
      LCOUNT      To count characters, words in a record
      REVERSE     To reverse content of a record.
   rearrange
      CHANGE      To change strings in records.
      SELECT      To select columns in a formatted report (also see Layout)
      SPECS       To reformat records in multiple ways. The most used stage in pipeline!
      XLATE       To translate characters in different ways
gateways
   DEAL        To write records to output streams in a round-robin fashion.
   FANINANY    To combine multiple input streams into one output stream.(processes inputs streams in parallel)
   FANIN       To combine multiple input streams into one output stream (processes one input stream at a time)
   FANOUT      To copy records from primary input stream to multiple output streams
   GATE        To pass records from input streams to output streams until stopped.
   GATHER      To pass records from all input streams to primary output stream in two ways.
   JUXTAPOSE   to prefix one or more records in its secondary input stream with a record from its primary input stream.
host
   command
      COMMAND     To run system command and wait for completion
      DAEMON      To start system command/process without waiting completion
lookup
   routines
      APL         To run APL commands and rectrieve result
      NOTES       To interact with Notes databases. (get/set documents, and other).
selection
   content
      ABBREV      To select records on abbreviation.
      ALL         To select records that satisfy a search criteria.
      FIND        To select records that begin with string
      LOCATE      To select records that contain a specified target string of characters.
      NFIND       To select records that don't begin with string
      NLOCATE     To select records that don't contain a specified target string of characters.
   groups
      BETWEEN     To select records between labels.
      DROP        To discard the first n(last n) records/bytes and select the remainder.
      FRLABEL     To select records from a label.
      FROMLABEL   To select records from a label.
      INSIDE      To select records inside targets
      TAKE        To select one or more records from the beginning or end of its primary input stream.
service
   program
      ?           Online Help (synonym for Help ).
      HELP        Online Help
      QUERY       To get pipeline information.
      RUNCASES    To run samples of stages defined in documentation.
sorters
   COLLATE     To compare two input streams containing master records and detail records
   LOOKUP      To find records in a reference.
   SORT        To sort records.


Stage: APPEND


Syntax

 
  >>----- APPEND ------- stage ---- parameters --------><
 

Purpose

 Use the APPEND stage command to copy records from its primary input stream to
 its primary output stream, and then invoke another stage command
 and write the records produced by that stage command
 to its primary output stream (if it is connected).

Operands

 stage
 		is the stage name you want to append to the pipeline.

 parameters
 		are the parameters to pass to the stage

Streams

 PRIMARY INPUT STREAM:  APPEND reads records from its primary input stream.

 PRIMARY OUTPUT STREAM:  APPEND copies its primary input stream records to its
 						  primary output stream.  APPEND then writes any output 
						  resulting from the specified stage command to its primary output stream.

Examples

Example 1

To display the string 'Hello World' and the content of the append.data , pass the following command: pipe "literal Hello World!append < Case_Append.data ! console " Case_Append.data
This is the content 
of a single file called: Case_Append.data

I've nothing to say ...so quit
Results
pipe "literal Hello World!append < Case_Append.data ! console  " 
Hello World
This is the content 
of a single file called: Case_Append.data
 
I've nothing to say ...so quit

Example 2

To append a trailer to a file, issue a similar pipeline command: pipe "< inputfile ! append literal * * * Trailer * * *! > outputfile"

Stage: FRTARGET


Syntax

 
 >>--.-- FRTARGET ----.-- stagecommand --.--------------.-------------><
     '-- FROMTARGet --'                  '-- operands --'
 
 

Purpose

 Use the FRTARGET stage command to select all records starting with the first
 record selected by a specified stage command.  FRTARGET invokes another stage
 command and rejects all records until the specified stage command selects a
 record.  FRTARGET passes records read from its primary input stream to the specified
 stage command until that stage command writes a record to its primary output
 stream.  Once this trigger record is written to the specified stage's primary
 output stream, FRTARGET copies the input record corresponding to the trigger
 record and shorts the remaining primary input stream to its own primary output
 stream.  It writes the unselected records to the secondary output stream, if
 it is connected.

Operands

 
 stagecommand
     is the name of a built-in stage command, or the name of a user-written
     stage command.  This specified stage command must support a connected
     primary input stream, a connected primary output stream, and a connected
     secondary output stream.  The stage command should produce one output record for each input
     record without delaying the records.  The stage command should also end
     without consuming the current record when it discovers that neither output
     stream is connected, and it should not consume the record it is writing
     when it encounters end of file on any output stream.
 
 operands
     are any operands valid for the specified built-in stage command or
     user-written stage command.

Streams

 
 PRIMARY INPUT STREAM:  FRTARGET reads records from its primary input stream
 and passes these records to the primary input stream of the specified stage
 command until the specified stage command writes a record to its primary
 output stream.  FRTARGET then shorts the primary input to its primary output,
 starting with the input record corresponding to the trigger record.
 
 PRIMARY OUTPUT STREAM:   FRTARGET shorts the first input record selected by
 the specified stage command (the trigger record) and the remaining primary
 input records to its primary output stream.
 
 SECONDARY OUTPUT STREAM:  If its secondary output stream is connected,
 FRTARGET copies to its secondary output stream all records that the specified
 stage command writes to its secondary output stream.  FRTARGET disconnects its
 secondary output stream when the specified stage command writes a record to
 its primary output stream.
 

Examples

 

Example 1

The following PIPE command selects all records beginning with the first one that contains the string abc and does not contain the string xyz: pipe "< TEST.FILE ! frtarget all /abc/ & ^ /xyz/ ! console"

Example 2

The following pipe command searches the file Frtarget_Test.data until it locates a set of numbers that does not contain a 3, which is the set 4 5 6 in this example. It then writes to the console the set 4 5 6 and all sets of numbers that follow this set. All sets of numbers which precede the set 4 5 6 are written to the secondary output stream of FRTARGET and then writed to the console (number 2). pipe "(end ?) < Case_Frtarget.data ! f: frtarget nlocate /3/ ! cons 1 ? f: ! cons 2" Below is the contents of the input file Frtarget_Test.data Case_Frtarget.data
1 2 3
2 3 4
3 4 5
4 5 6
5 6 7
3 6 7
Results
                                               
pipe "(end ?) < Case_Frtarget.data ! f: frtarget nlocate /3/ ! cons 1 ? f: ! cons 2"
Console(2):1 2 3
Console(2):2 3 4
Console(2):3 4 5
Console(1):4 5 6
Console(1):5 6 7
Console(1):3 6 7

Stage: FROMTARGET


Syntax

 
 >>--.-- FRTARGET ----.-- stagecommand --.--------------.-------------><
     '-- FROMTARGet --'                  '-- operands --'
 
 

Purpose

 Use the FRTARGET stage command to select all records starting with the first
 record selected by a specified stage command.  FRTARGET invokes another stage
 command and rejects all records until the specified stage command selects a
 record.  FRTARGET passes records read from its primary input stream to the specified
 stage command until that stage command writes a record to its primary output
 stream.  Once this trigger record is written to the specified stage's primary
 output stream, FRTARGET copies the input record corresponding to the trigger
 record and shorts the remaining primary input stream to its own primary output
 stream.  It writes the unselected records to the secondary output stream, if
 it is connected.

Operands

 
 stagecommand
     is the name of a built-in stage command, or the name of a user-written
     stage command.  This specified stage command must support a connected
     primary input stream, a connected primary output stream, and a connected
     secondary output stream.  The stage command should produce one output record for each input
     record without delaying the records.  The stage command should also end
     without consuming the current record when it discovers that neither output
     stream is connected, and it should not consume the record it is writing
     when it encounters end of file on any output stream.
 
 operands
     are any operands valid for the specified built-in stage command or
     user-written stage command.

Streams

 
 PRIMARY INPUT STREAM:  FRTARGET reads records from its primary input stream
 and passes these records to the primary input stream of the specified stage
 command until the specified stage command writes a record to its primary
 output stream.  FRTARGET then shorts the primary input to its primary output,
 starting with the input record corresponding to the trigger record.
 
 PRIMARY OUTPUT STREAM:   FRTARGET shorts the first input record selected by
 the specified stage command (the trigger record) and the remaining primary
 input records to its primary output stream.
 
 SECONDARY OUTPUT STREAM:  If its secondary output stream is connected,
 FRTARGET copies to its secondary output stream all records that the specified
 stage command writes to its secondary output stream.  FRTARGET disconnects its
 secondary output stream when the specified stage command writes a record to
 its primary output stream.
 

Examples

 

Example 1

The following PIPE command selects all records beginning with the first one that contains the string abc and does not contain the string xyz: pipe "< TEST.FILE ! frtarget all /abc/ & ^ /xyz/ ! console"

Example 2

The following pipe command searches the file Frtarget_Test.data until it locates a set of numbers that does not contain a 3, which is the set 4 5 6 in this example. It then writes to the console the set 4 5 6 and all sets of numbers that follow this set. All sets of numbers which precede the set 4 5 6 are written to the secondary output stream of FRTARGET and then writed to the console (number 2). pipe "(end ?) < Case_Frtarget.data ! f: frtarget nlocate /3/ ! cons 1 ? f: ! cons 2" Below is the contents of the input file Frtarget_Test.data Case_Frtarget.data
1 2 3
2 3 4
3 4 5
4 5 6
5 6 7
3 6 7
Results
                                               
pipe "(end ?) < Case_Frtarget.data ! f: frtarget nlocate /3/ ! cons 1 ? f: ! cons 2"
Console(2):1 2 3
Console(2):2 3 4
Console(2):3 4 5
Console(1):4 5 6
Console(1):5 6 7
Console(1):3 6 7

Stage: IN


Syntax

 >>-----.---- IN ----.---------><
        '-- PIPEIN --'
 

Purpose

 Use the IN stage when you are using pipeline class in a Java program 
 and you wish to pass it data in another way as VAR and STEM.
 
 The simple way to use it is, in your java code:
 
   Pipeline pipe=new Pipeline("in!specs ...!...");	// Define the pipeline  
   pipe.start(); 										// launch the pipe thread	
	try {
		pipe.getPipeIn().writeLine("Hello");			// write string to pipeline
		pipe.getPipeIn().writeLine("I'm lolo");		// write another string to pipeline
		pipe.getPipeIn().close();						// close the stream 
	} catch (PipelineIOException pioe) {				// catch in case of stream problems 
		pioe.printStackTrace();							// print error 
	}
 

Operands

(operands not available)

Streams

 PRIMARY INPUT STREAM:  IN reads records from its primary input stream, that is
 connected to the user java program where the pipeline class is used.

 PRIMARY OUTPUT STREAM:   IN writes to its primary output stream input
 all the records.

Examples

Example 1

The following Java program runs a pipeline command and pass string to the pipeline via the IN stage For facilities...the Case_In.java extends PipelineStage for using it with the Java stage for immediate compilation and execution. Case_In.java
import com.ibm.lparis.pipeline.core.*;
import com.ibm.lparis.pipeline.core.exceptions.*;
public class Case_In extends Pipeline_Stage { 

   public void runStage() throws StageException {
      Pipeline pipe=new Pipeline("in!specs /==>/ 1 1-* nw!cons"); 
      pipe.start();
      try {
         pipe.getPipeIn().writeLine("Hey Jude...");  
         pipe.getPipeIn().writeLine("O bladi o blada ...");  
         pipe.getPipeIn().close(); 
      } catch (PipelineIOException pioe) { 
         pioe.printStackTrace(); 
      } 
   }


}
Results
pipe "(end ?)java Case_In!hole" 
==> Hey Jude...
==> O bladi o blada ...

Stage: OUT


Syntax

 >>-----.---- OUT ----.---------><
        '-- PIPEOUT --'
 

Purpose

 Use the OUT stage when you are using pipeline class in a Java program 
 and you wish to get data in another way as VAR and STEM.
 
 The simple way to use it is, in your java code:
 
   Pipeline pipe=new Pipeline("....!out");			// Define the pipeline  
   pipe.start(); 										// launch the pipe thread	
	try {
		while (p.getPipeOut().isConnected()) {			// while stream is connected...
			System.out.println("Data="+p.getPipeOut().readLine());	// get data and display them
		}
	} catch (PipelineIOException pioe) {				// catch in case of stream problems 
		pioe.printStackTrace();							// print error 
	}
 

Operands

(operands not available)

Streams

 PRIMARY INPUT STREAM:  OUT reads records from its primary input stream and
 passes them to the Java program where the pipeline class is used,
 using the getPipeOut() method.

 PRIMARY OUTPUT STREAM:   OUT writes records to internal buffer that is accessed
 by the getPipeOut() method.

Examples

Example 1

The following Java program runs a pipeline command and get retrive records from pipeline using the OUT stage. For facilities...the Case_Out.java extends PipelineStage for using it with the Java stage for immediate compilation and execution. Case_Out.java
import com.ibm.pipeline.*;
public class Case_Out extends PipelineStage { 

   public void runStage() {
      Pipeline pipe=new Pipeline("range 10!split!out"); // generate number 1 to 9 and split line
      pipe.start();	// start the pipeline
      Object data=null; 
      try {
         while ( (data=pipe.getPipeOut().readLine()) != null ) {       // loop until stream connected... 
             System.out.println("data="+data);  // display data
		  } 
      } catch (PipelineIOException pioe) { 
         pioe.printStackTrace(); 
      } 
   }


}
Results
pipe "(end ?)java Case_Out!hole" 
data=0
data=1
data=2
data=3
data=4
data=5
data=6
data=7
data=8
data=9

Stage: PREFACE


Syntax

 
 >>-- PREFACE --- stagecommand --.--------------.------------------------------><
                                 '-- operands --' 
 
 

Purpose

 
 Use the PREFACE stage command to invoke another stage command, 
 write the records produced by that stage command 
 to its primary output stream, and then copy all records from its
 primary input stream to its primary output stream.
 

Operands

 
 stagecommand
     is the name of a built-in stage command. 
     The stagecommand must be a stage command you can specify
     as a first stage in a pipeline.
 
 operands
     are any operands valid for the specified built-in stage command
 

Streams

 
 PRIMARY INPUT STREAM:  PREFACE reads records from its primary input stream.
 
 PRIMARY OUTPUT STREAM:  PREFACE writes any output resulting from the specified
 stage command to its primary output stream.  PREFACE
 then copies its primary input stream records to its primary output stream.
 

Examples

Example 1

In this example, PREFACE writes a file to its primary output stream and then copies its primary input stream to its primary output stream. pipe "< Case_Preface.data ! preface < Case_Preface.header ! console" Case_Preface.data
Kristin Potter          B         C         A         A
Jeremy Underwood        B         B         B         A
Kyle White              C         A         B         B
Molly Yelverton         A         A         B         A
Case_Preface.header
    Name              Math     English   Science    History
-----------------     ----     -------   -------    -------
Results
                                               
pipe "< Case_Preface.data ! preface < Case_Preface.header ! console" 
    Name              Math     English   Science    History
-----------------     ----     -------   -------    -------
Kristin Potter          B         C         A         A
Jeremy Underwood        B         B         B         A
Kyle White              C         A         B         B
Molly Yelverton         A         A         B         A

Stage: PIPEIN


Stage in development

Syntax

 >>-----.---- IN ----.---------><
        '-- PIPEIN --'
 

Purpose

 Use the IN stage when you are using pipeline class in a Java program 
 and you wish to pass it data in another way as VAR and STEM.
 
 The simple way to use it is, in your java code:
 
   Pipeline pipe=new Pipeline("in!specs ...!...");	// Define the pipeline  
   pipe.start(); 										// launch the pipe thread	
	try {
		pipe.getPipeIn().writeLine("Hello");			// write string to pipeline
		pipe.getPipeIn().writeLine("I'm lolo");		// write another string to pipeline
		pipe.getPipeIn().close();						// close the stream 
	} catch (PipelineIOException pioe) {				// catch in case of stream problems 
		pioe.printStackTrace();							// print error 
	}
 

Operands

(operands not available)

Streams

 PRIMARY INPUT STREAM:  IN reads records from its primary input stream, that is
 connected to the user java program where the pipeline class is used.

 PRIMARY OUTPUT STREAM:   IN writes to its primary output stream input
 all the records.

Examples

Example 1

The following Java program runs a pipeline command and pass string to the pipeline via the IN stage For facilities...the Case_In.java extends PipelineStage for using it with the Java stage for immediate compilation and execution. Case_In.java
import com.ibm.lparis.pipeline.core.*;
import com.ibm.lparis.pipeline.core.exceptions.*;
public class Case_In extends Pipeline_Stage { 

   public void runStage() throws StageException {
      Pipeline pipe=new Pipeline("in!specs /==>/ 1 1-* nw!cons"); 
      pipe.start();
      try {
         pipe.getPipeIn().writeLine("Hey Jude...");  
         pipe.getPipeIn().writeLine("O bladi o blada ...");  
         pipe.getPipeIn().close(); 
      } catch (PipelineIOException pioe) { 
         pioe.printStackTrace(); 
      } 
   }


}
Results
pipe "(end ?)java Case_In!hole" 
==> Hey Jude...
==> O bladi o blada ...

Stage: PIPEOUT


Stage in development

Syntax

 >>-----.---- OUT ----.---------><
        '-- PIPEOUT --'
 

Purpose

 Use the OUT stage when you are using pipeline class in a Java program 
 and you wish to get data in another way as VAR and STEM.
 
 The simple way to use it is, in your java code:
 
   Pipeline pipe=new Pipeline("....!out");			// Define the pipeline  
   pipe.start(); 										// launch the pipe thread	
	try {
		while (p.getPipeOut().isConnected()) {			// while stream is connected...
			System.out.println("Data="+p.getPipeOut().readLine());	// get data and display them
		}
	} catch (PipelineIOException pioe) {				// catch in case of stream problems 
		pioe.printStackTrace();							// print error 
	}
 

Operands

(operands not available)

Streams

 PRIMARY INPUT STREAM:  OUT reads records from its primary input stream and
 passes them to the Java program where the pipeline class is used,
 using the getPipeOut() method.

 PRIMARY OUTPUT STREAM:   OUT writes records to internal buffer that is accessed
 by the getPipeOut() method.

Examples

Example 1

The following Java program runs a pipeline command and get retrive records from pipeline using the OUT stage. For facilities...the Case_Out.java extends PipelineStage for using it with the Java stage for immediate compilation and execution. Case_Out.java
import com.ibm.pipeline.*;
public class Case_Out extends PipelineStage { 

   public void runStage() {
      Pipeline pipe=new Pipeline("range 10!split!out"); // generate number 1 to 9 and split line
      pipe.start();	// start the pipeline
      Object data=null; 
      try {
         while ( (data=pipe.getPipeOut().readLine()) != null ) {       // loop until stream connected... 
             System.out.println("data="+data);  // display data
		  } 
      } catch (PipelineIOException pioe) { 
         pioe.printStackTrace(); 
      } 
   }


}
Results
pipe "(end ?)java Case_Out!hole" 
data=0
data=1
data=2
data=3
data=4
data=5
data=6
data=7
data=8
data=9

Stage: RUNPIPE


Syntax

 
  >>----- RUNPIPE -------><
 

Purpose

 
 Use the RUNPIPE stage command to issue pipelines.  RUNPIPE reads records
 from its primary input stream and issues them as pipelines in the same way
 that the PIPE command does, creating a new pipeline set for each record it
 reads.  Each pipeline issued by RUNPIPE runs until it completes.
 
 A RUNPIPE stage cannot be the first stage of a pipeline.

Operands

(operands not available)

Streams

 
 PRIMARY INPUT STREAM:  RUNPIPE reads records from its primary input stream.
 The input records must be in the same format as the string of operands and
 options on a PIPE command.
 
 PRIMARY OUTPUT STREAM:  n/a in this current version.

Examples

Example 1

To interpret user input as a pipeline command, run the following: pipe "cons eof /q/ ! runpipe" This is the pipeline command that is started when you execute pipe without any parameter. ¤ cons eof /q/ means all user inputs are passed to runpipe until the q character is entered. ¤ runpipe execute the user input as a pipeline command.

Example 1

Results
                                               
pipe "literal (sep §)literal Salut§cons  !runpipe  " 
Salut

Stage: RUNFILE


Syntax

 
  >>----- RUNFILE ----.-----------------.---><
                      '--- inputfile ---'
 

Purpose

 
 Use the RUNFILE stage command to issue pipelines.  Pipeline commands
 are read from inputfile if given in parameter or read from
 a filepath read from its input stream.
 

Operands

 inputfile
 		is the name of the file containing the pipeline command to run.

       if it doesn't exist, RUNFILE read its primary input stream to get inputfile. 

Streams

 
 PRIMARY INPUT STREAM:  RUNFILE reads records from its primary input stream if connected.
 The input records must contain valid filepath. Then RUNFILE executes the pipeline command
 defined in the inputfile.
 
 PRIMARY OUTPUT STREAM:  n/a in this current version.

Examples

Example 1

To run a long pipeline command contained in the file SAMPLE.PIPE, run the following: pipe "literal SAMPLE.PIPE !runfile " or pipe "runfile SAMPLE.PIPE " or pipe "-f SAMPLE.PIPE" SAMPLE.PIPE
#  
# sample file for testing runfile stage 
# 
  literal Hello world         # put 'Hello world' into pipeline
! specs /=>/ 1 1-* nw         # reformat record 
! cons                        # display to console 
Running the command displays the following output: Results
                                               
pipe "literal SAMPLE.PIPE ! runfile !cons " 
=> Hello world
SAMPLE.PIPE
Important: # is the comment character You can comment stages by using # at the end of the stage Forbidden to comment pipe options '(end ?)' and pipe separator '?'
+++ Stage 'SUB' not in Pipeline core system.

Stage: ADDPIPE


Stage for simulating pipeline command

Syntax

(syntax not available)

Purpose

(purpose not available)

Operands

(operands not available)

Streams

(streams not available)

Examples

(examples not available)
+++ Stage 'SUB' not in Pipeline core system. +++ Stage 'CALLPIPE' not in Pipeline core system.

Stage: <bin


Syntax

 
  >>----- <bin ----.----- fileid ------.-------><
                   '--- remote_file ---'			
 
  remote_file:
  >--- protocol -- :// -- hostname ---.----------.----.--------------.---><
                                      '-- port --'    '--- fileid ---'     
 

Purpose

 Use the <bin stage command to read the contents of a 'binary' file into a pipeline. 
 <bin reads the specified binary file (per 1024 blocks) and writes the records 
 to its primary output stream if it is connected.
 A <bin stage can be used only as the first stage of a pipeline.

Operands

 fileid
 		is the name of the file you want to read.
 		(File is read by 1024 bytes blocks)

 protocol
 		is the name of the protocol to be used when reading a remote file.
 		ex: http.

 hostname
 		is the name of the host to be reached for remote file.

 port
 		is the optional port number to be used.

Streams

 PRIMARY INPUT STREAM:		n/a

 PRIMARY OUTPUT STREAM:	<bin writes the records read from the file to its primary output stream.

Examples

Example 1

To read binary file and count characters, enter <bin pipeline.jar ! count chars ! cons

Example 2

To read executable from remote system and write it on my disk: <bin http://host/executableFile ! >bin localExecutable

Stage: <


Syntax

 
  >>----- < ----.----- fileid ------.-------><
                '--- remote_file ---'			
 
  remote_file:
  >--- protocol -- :// -- hostname ---.----------.----.--------------.---><
                                      '-- port --'    '--- fileid ---'     
 

Purpose

 Use the < stage command to read the contents of a file into a pipeline. 
 < reads the specified file and writes the records 
 to its primary output stream if it is connected.
 A < stage can be used only as the first stage of a pipeline.

Operands

 fileid
 		is the name of the file you want to read.

 protocol
 		is the name of the protocol to be used when reading a remote file.
 		ex: http.

 hostname
 		is the name of the host to be reached for remote file.

 port
 		is the optional port number to be used.

Streams

 PRIMARY INPUT STREAM:		n/a

 PRIMARY OUTPUT STREAM:	< writes the records read from the file to its primary output stream.

Examples

Example 1:

To count lines and words of my autoexec.bat file: < c:\autoexec.bat !count lines words !cons

Example 2:

To retrieve all the javascript code from the IBM intranet HomePage: < http://w3.ibm.com ! between §<script§ §</script§ ! cons

Example 3

In this example, we have a report file REPORT.DAT containing data. We read it and count character in it. The figures show the input file and the result after entering the following PIPE command: pipe "< REPORT.DAT ! count chars ! console" REPORT.DAT
Name        Address              City           State   
----------- -------------------- -------------- -----------------
John M.     40 Love Court        Douglaston     New York
Arnold P.   350 Yard Drive       Pebble Beach   California
Joe F.      111 Ringside Street  Pittsburgh     Pennsylvania
Earl A.     24 Bowling Lane      Cincinnati     Ohio
Larry B.    3 Point Road         Boston         Massachusetts
Mike S.     20 Shortstop Road    Philadelphia   Pennsylvania
Joe N.      19 Jet Drive         New York       New York
Running the command displays the following output: Results
                                               
pipe "< REPORT.DAT ! count chars ! console" 
524

Stage: >>bin


Syntax

 
  >>----- >>bin ------- fileid ----------><
 
 

Purpose

 Use the >>bin stage command to write to (append to or create) a binary file.
 A >>bin stage cannot be the first stage of a pipeline.
 
 >>bin writes all records from its primary input stream to the specified file.
 If the file exists, >>bin appends the records from its primary
 input stream to the file.  If the file does not exist, >>bin creates a new file
 containing the records from its primary input stream.  If the primary output
 stream is connected, >>bin writes all records from
 its primary input stream to its primary output stream.
 

Operands

 fileid
 		is the name of the file you want to append binary data.

Streams

 PRIMARY INPUT STREAM:  >>bin reads records from its primary input stream.
 
 SECONDARY INPUT STREAM:  After its primary input stream reaches end of file,
 >>bin reads records from its secondary input stream, if it is connected.
 
 PRIMARY OUTPUT STREAM:  >>bin writes its primary input stream records
 to its primary output stream.
 
 SECONDARY OUTPUT STREAM:  If its secondary output stream is connected, >>bin
 writes its secondary input stream records to its secondary output stream.

Examples

Example 1:
	To append binary data to other:
 
	<bin binFile ! >>bin outBinFile


Stage: >>


Syntax

 
  >>----- >> ------- fileid ----------><
 
 

Purpose

 Use the >> stage command to write to (append to or create) a file.  A >>
 stage cannot be the first stage of a pipeline.
 
 >> writes all records from its primary input stream to the specified file.
 If the file exists, >> appends the records from its primary
 input stream to the file.  If the file does not exist, >> creates a new file
 containing the records from its primary input stream.  If the primary output
 stream is connected, >> writes all records from
 its primary input stream to its primary output stream.
 
 After the primary input stream reaches end of file, if the secondary input
 stream is connected, >> overwrites the first records of the specified file
 with the non-null records from its secondary input stream.  If the secondary
 output stream is connected, >> writes all records from its secondary input
 stream to its secondary output stream.

Operands

 fileid
 		is the name of the file you want to append records.

Streams

 PRIMARY INPUT STREAM:  >> reads records from its primary input stream.
 
 SECONDARY INPUT STREAM:  After its primary input stream reaches end of file,
 >> reads records from its secondary input stream, if it is connected.
 
 PRIMARY OUTPUT STREAM:  >> writes its primary input stream records
 to its primary output stream.
 
 SECONDARY OUTPUT STREAM:  If its secondary output stream is connected, >>
 writes its secondary input stream records to its secondary output stream.

Examples

Example 1:
	To append data to an existing file:
 
	literal Data appended to file ! >> outFile


Stage: >bin


Syntax

 
  >>----- >bin ------- fileid ----------><
 
 

Purpose

 Use the >bin stage command to create a binary file or replace the contents of a binary file.
 A >bin stage cannot be the first stage of a pipeline.
 
 >bin writes all records from its primary input stream to the
 specified file.  If the specified file does not exist, >bin creates a new file
 containing the records from its primary input stream.  If the specified file
 already exists, >bin replaces the contents of
 the file with the records read from its primary input stream.
 If its primary output stream is connected, >bin copies all
 records from its primary input stream to its primary output stream.
 	
 After its primary input stream reaches end of file, if its secondary input
 stream is connected, >bin overwrites the first records of the specified file with
 the records from its secondary input stream.  If its secondary output stream
 is connected, >bin copies all records from its secondary input stream to its
 secondary output stream.
 

Operands

 fileid
 		is the name of the file you want to write in.

Streams

 PRIMARY INPUT STREAM:  >bin reads records from its primary input stream.
 
 SECONDARY INPUT STREAM:  After its primary input stream reaches end of file, >bin
 reads records from its secondary input stream, if it is connected.
 
 PRIMARY OUTPUT STREAM:  >bin copies its primary input stream records
 to its primary output stream.
 
 SECONDARY OUTPUT STREAM:  If its secondary output stream is connected, >bin
 copies its secondary input stream records to its secondary output stream.  >bin
 reads records from its secondary input stream only after no more records are
 available to read from its primary input stream.

Examples

Example 1:
	To make a full copy a binary file:
 
	<bin binFile ! >bin outBinFile


Stage: >


Syntax

 
  >>----- > ------- fileid ----------><
 
 

Purpose

 Use the > stage command to create a file or replace the contents of a file.
 A > stage cannot be the first stage of a pipeline.
 
 > writes all records from its primary input stream to the
 specified file.  If the specified file does not exist, > creates a new file
 containing the records from its primary input stream.  If the specified file
 already exists, > replaces the contents of
 the file with the records read from its primary input stream.
 If its primary output stream is connected, > copies all
 records from its primary input stream to its primary output stream.
 	
 After its primary input stream reaches end of file, if its secondary input
 stream is connected, > overwrites the first records of the specified file with
 the records from its secondary input stream.  If its secondary output stream
 is connected, > copies all records from its secondary input stream to its
 secondary output stream.
 

Operands

 fileid
 		is the name of the file you want to write in.

Streams

 PRIMARY INPUT STREAM:  > reads records from its primary input stream.
 
 SECONDARY INPUT STREAM:  After its primary input stream reaches end of file, >
 reads records from its secondary input stream, if it is connected.
 
 PRIMARY OUTPUT STREAM:  > copies its primary input stream records
 to its primary output stream.
 
 SECONDARY OUTPUT STREAM:  If its secondary output stream is connected, >
 copies its secondary input stream records to its secondary output stream.  >
 reads records from its secondary input stream only after no more records are
 available to read from its primary input stream.

Examples

Example 1:
	To create a file 'oneline' that contains a single line:
 
	literal Single line ! > oneline


Stage: GETFILES


Syntax

 
 
 >>-- GETfiles ------------------><
 
 

Purpose

 
 Use the GETFILES stage command to read a list of files into a pipeline.
 GETFILES reads records from its primary input stream.  Each record specifies
 the file identifier of a file to be read.
 
 If its primary output stream is connected, GETFILES writes to its primary
 output stream the contents of each file that it reads.
 
 

Operands

(operands not available)

Streams

 
 PRIMARY INPUT STREAM:  GETFILES reads records from its primary input stream.
 The primary input stream record must be a valid file specification (see < stage)
 
 PRIMARY OUTPUT STREAM:  GETFILES writes to its primary output stream the
 contents of each file read.
 

Examples

 

Example 1

Given the PARTS.LIST file, the following pipeline command copies the contents of all files in the list into one output file: pipe "< PARTS.LIST ! getfiles ! > COMBINED.FILES" PARTS.LIST ===== * * * Top of File * * * ===== PART1.FILE ===== PART2.FILE ===== PART3.FILE ===== PART4.FILE ===== * * * End of File * * *

Example 2

The following command searches all files in the current directory for records containing the string SOFTBALL: pipe "command ls ! getfiles ! locate /SOFTBALL/ ! console" Note: 'ls' runs under Aix,Linux,...

Stage: BEAT


Syntax

 
 >>-- BEAT ------ number -----.----------------.-------------------------><
                              '--- /string/ ---'   
 

Purpose

 Use the BEAT as a 'heartbeat monitor'.
 This can be used in conjunction with any device driver stage which collects
 data from device (tcp/ip listener, remote file reader, ...)
 BEAT stops when it discovers its secondary output record is disconnected...

Operands

 number
     is the interval of time for records to arrive.
     number is defined in milliseconds.
 
 /(diagonal)
     signifies any nonblank delimiting character that does not appear in
     string.
 
 string
     specifies a string of characters to be written to the secondary output stream.
 

Streams

 PRIMARY INPUT STREAM:  BEAT reads records from its primary input stream.
 
 PRIMARY OUTPUT STREAM:  BEAT copies input records that arrive before the specified interval.
 
 SECONDARY OUTPUT STREAM:  If no input record arrives before specified interval,
 BEAT writes a record (null or the string defined) each time the interval expires.

Examples

Example 1

This sample shows how operate the beat stage. The first sample pipe command: (end ?) literal +3 ***** ! delay ! b:beat 5000 /No command arrives after 5s/ ! cons ? b:!cons displays following result: +3 ***** 'literal' stage defines the string '+3 *****' 'delay' stage gets '+3 *****' and waits for 3 seconds before to push record to its output 'beat' stage waits for 5000ms ...so as the previous stage push record after 3 seconds, the beat stage copy record into its primary output stream. for other stages and connectors, see documentation Results
pipe "(end ?) literal +3 ***** ! delay ! b:beat 5000 /No command arrives after 5s/ ! cons ? b:!cons" 
+3 *****

Example 2

This sample shows how operate the beat stage. The first sample pipe command: (end ?) literal +6 *****!delay!b:beat 5000 /No command arrives after 5s/!cons ? b:!cons displays following result: No command arrives after 5s +6 ***** As 'delay' stage delays record xmission of 6 seconds, beat sends the string 'No command arrives after 5s' on its secondary output stream. after the 6 seconds, the record from delay is push to beat primary output stream. Results
pipe "(end ?) literal +6 *****!delay!b:beat 5000 /No command arrives after 5s/!cons ? b:!cons" 
No command arrives after 5s
+6 *****

Stage: BLUEPAGES


Syntax

 >>-- BLUEPAGES ---.---------------------.---| action |------------.-------------.----><
                   '--- SEParator car ---'                         | <--- , ---< |
                                                                   '-- colname --'
 
 action:
 |---------.--- GETPERSONBYCNUM ------------.-------|
           |--- GETPERSONSBYSERIAL ---------|
           |--- GETPERSONSBYNAMELITE -------|
           |--- GETPERSONSBYNAME -----------|
           |--- GETPERSONSBYNOTESIDLITE ----|
           |--- GETPERSONSBYNOTESID --------|
           |--- GETPERSONSBYINTERNET -------|
           |--- GETMGRCHAINOF --------------|
           |--- GETDIRECTREPORTSOF ---------|
           |--- GETDIRECTREPORTSOFLITE -----|
           |--- GETDEPARTMENTMEMBERS -------|
           '--- GETDEPARTMENTMEMBERSLITE ---'
 

Purpose

 Use the BLUEPAGES to get data from the centralized BluePages directory.
 
 BLUEPAGES get records from its input stream and for each one, apply the action given
 by the user and writes output to its primary output stream.
 Input data must correspond to the type of action:
 (see BluePages documentation for detail)
 
 If you do not specify column names, then the output is the toString() output
 from BluePages api.
 
 When you specify column names, you can separate them with comma.
 
 Default separator for output when columns specified is blank, you can force it
 to a special character by specifying SEParator argument.

Operands

 SEParator
     signifies you want to specify a character as field separator for 
     the output when you specify column names.
 
 car
     defines the character you want to use as output field separator
     Default is blank.
 
 colname
     specifies the column name you want to retrieve from bluepages.
     
     You can specify more than one by separating them with a comma.
 

Streams

 PRIMARY INPUT STREAM:  BLUEPAGES reads records from its primary input stream.
 Records must be in the proper BluePages format following the action taken.
 
 PRIMARY OUTPUT STREAM:  BLUEPAGES retrieve data fro mdirectory and write them to 
 its primary output stream.

Examples

Example 1

To get name and emailaddress of a list of employee numbers + country code: employees.cnum file content: 829119897 925355897 917630744 pipe "< employees.cnum!bluepages getpersonbycnum name,dept,emailaddress!cons" Results are: Ralston, Debora A. (Debi) 4EGA CN=Debi Ralston/OU=St Louis/O=IBM@IBMUS Rodriguez, Peter BBKA CN=Peter Rodriguez/OU=Mountain View/O=IBM@IBMUS Aalhad, Saraf A 0053 CN=Aalhad A Saraf/OU=India/O=IBM@IBMIN If you want to apply a separator character for a further string importation in 123 or for reformatting with pipeline: pipe "< employees.cnum!bluepages sep ; getpersonbycnum name,dept,emailaddress!cons" Results are: Ralston, Debora A. (Debi);4EGA;CN=Debi Ralston/OU=St Louis/O=IBM@IBMUS; Rodriguez, Peter;BBKA;CN=Peter Rodriguez/OU=Mountain View/O=IBM@IBMUS; Aalhad, Saraf A;0053;CN=Aalhad A Saraf/OU=India/O=IBM@IBMIN;

Stage: CLIPBOARD


Syntax

 
  >>----- CLIPBOARD-----------------><
 

Purpose

 
 Use the CLIPBOARD stage command to read lines from or write lines to the
 clipboard.
 
 When CLIPBOARD is the first stage of a pipeline, CLIPBOARD reads records from the
 clipboard and writes the records to its primary output stream if it is
 connected.  
 
 When CLIPBOARD is not the first stage of a pipeline, CLIPBOARD reads records from
 its primary input stream and writes them to the terminal and to its primary
 output stream, if it is connected.
 

Operands

(operands not available)

Streams

 
 PRIMARY INPUT STREAM:  CLIPBOARD read data from its primary input stream and 
 write them to the clipboard.
 If CLIPBOARD is the first stage, then it reads data from the clipboard.
 
 PRIMARY OUTPUT STREAM:  CLIPBOARD passes data to primary output stream.

Examples

(examples not available)

Stage: DB2


Syntax

 
 
 >>- DB2 -----|db|----|user|----|psw|---- query ---------->
 
 
 
 db:
 |--.--- DATABASE--.-------- dbname -----------------------|
    '----- DB -----'
 
 user:
 |----- USER --------- username -----------------------|
 
 psw:
 |--.--- PASSword --.-------- password -----------------------|
    '----- PSW -----'
 
 

Purpose

 Use the DB2 stage command to run a SQL command against a DB2 database.
 This stage is a sample stage that only uses sun.jdbc.odbc.JdbcOdbcDriver. 

Operands

 query
     The sql query to perform.

Streams

 INPUT STREAMS:  n/a
 
 PRIMARY OUTPUT STREAM:  DB2 writes query results to its primary
 output stream.
 

Examples

 

Example 1

To get system tables from DB2... pipe " db2 MASTERDB2 user admin psw xxxxx select * from system.systeables "

Stage: DELAY


Syntax

 
 >>-- DELAY -------------------------------------------------------------------><
 

Purpose

 Use the DELAY stage command to wait until a particular time of day or until
 after a specified interval of time has passed to copy the record.  DELAY reads
 a record containing a time or time interval from its primary input stream,
 waits until the specified time, writes the record to its primary output stream
 (if it is connected), and then reads the next record from its primary input
 stream.
 
 The first word of each input record specifies a time interval or a time of
 day.  The remainder of the record is not inspected.  A DELAY stage cannot be
 the first stage of a pipeline.

Operands

(operands not available)

Streams

 
 PRIMARY INPUT STREAM:  DELAY reads records from its primary input stream.
 DELAY discards null or blank input records.  The input records must contain a
 time interval or time of day as first word.  To specify a time interval, the first word
 of the input records must be in the following format:
 
 
                                                 
 >>-- + --.-----------------------------.----- ss --><
          |                             |
          '--.------------.------ mm: --'
             |            |
             '----- hh: --'
 
 
 +  indicates that the time is relative to the current time.
 
 :  separates the hours, minutes, and seconds (hh, mm, ss).
 
 hh represents hours.
 
 mm represents minutes.
 
 ss represents seconds.
 
 To specify a time of day, the first blank-delimited word of each input record
 must be in the following format:
 
 >>-- hh --.----------------------------.--><
           |                            |
           '----- :mm --.------------.--'
                        |            |
                        '----- :ss --'
 
 :  separates the hours, minutes, and seconds (hh, mm, ss).
 
 hh represents hours.
 
 mm represents minutes.
 
 ss represents seconds.
 
 PRIMARY OUTPUT STREAM:  DELAY copies primary input stream records to its
 primary output stream.

Examples

 

Example 1

The following PIPE command uses the DELAY stage command to postpone running a linux command for 15 seconds: pipe "literal +15 ! delay ! specs /ls -al/ 1 ! command ! console" After 15 seconds DELAY passes a record to SPECS. SPECS writes the character string ls -al to its output stream, Linux processes the ls -al command, and CONSOLE writes the data to the terminal.

Example 2

You can use DUPLICATE in conjunction with DELAY to repeat a command a specified number of times. In the following PIPE command, the Linux w (who) command is processed a total of five times and there is a 1 minute and 30 second delay between each time it is run: pipe "literal +1:30 ! duplicate 4 ! delay ! spec /w/ 1 ! command ! console" Note also that the first w command is processed after 1 minute and 30 seconds.

Stage: HOLE


Syntax

 
 
 >>-- HOLE ------------------><
 
 

Purpose

 
 Use the HOLE stage command to read all input records and consume them.  HOLE
 reads records from all its connected input streams and does not write records
 to any output streams.  The output stream remains connected until all input
 streams reach the end of file.
 
 

Operands

(operands not available)

Streams

 
 INPUT STREAMS:  HOLE reads records from all connected input streams.
 
 PRIMARY OUTPUT STREAM:  Although HOLE does not write any records to its
 primary output stream, the output streams stay connected until all input
 streams reach end of file.
 

Examples

Example 1

You want to display records (from a file) that do not contain a particular string and you forgot the nlocate stage existence...(why not??) by issuing: pipe "(end ?) < HOLE.FILE ! l: locate /hole/ ! hole ? l:!cons" HOLE.FILE
The black holes can have many definitions 
depending on age, behaviour, culture, etc.
     
¤ A scientific thinks about universe, so in astro black holes. 
¤ Freud could think about a think abscence
¤ etc... up to you to find other meaning...and there are
Results
                                               
pipe "(end ?) < HOLE.FILE ! l: locate /hole/ ! hole ? l:!cons" 
depending on age, behaviour, culture, etc.
 
¤ Freud could think about a think abscence
¤ etc... up to you to find other meaning...and there are

Stage: JAVAP


Stage in development

Syntax

(syntax not available)

Purpose

(purpose not available)

Operands

(operands not available)

Streams

(streams not available)

Examples

(examples not available)

Stage: JAVA


Syntax

(syntax not available)

Purpose

(purpose not available)

Operands

(operands not available)

Streams

(streams not available)

Examples

Example 1

MyTest.java
import com.ibm.pipeline.*;
public class MyTest extends PipelineStage {

   public void initStage(String parms) {
      stageParameters=parms;
   }

   public void runStage() {
      out("starting...");
      out("targuments="+stageParameters);

      String data=null;
      out("dispatch records from primary input stream to primary and secondary output stream");
      out("...first record to primary output, second to secondary output, third to primary, ...");
      select("input",0); 
      int o=1;
      data=readto();
      while (rc==0) {
	 o=(o==1?0:1);
         select("output",o);
         output(data);
         data=readto();
      }

      out("dispatch records from secondary input stream to primary and secondary output stream");
      out("...first record to primary output, second to secondary output, third to primary, ...");
      select("input",1); 
      o=1;
      data=readto();
      while (rc==0) {
	 o=(o==1?0:1);
         select("output",o);
         output(data);
         data=readto();
      }
      out("ending...");
   }

   void out(String txt) {
       System.out.println("MyTest 	"+txt);
   }

}
Results
pipe "(end ?)literal there are records from input 1!split!j:java MyTest with parameters !cons 1 ? literal secondary inputstream records2!split!j:!cons 2" 
MyTest 	starting...
MyTest 	targuments=with parameters
MyTest 	dispatch records from primary input stream to primary and secondary output stream
MyTest 	...first record to primary output, second to secondary output, third to primary, ...
Console(1):there
Console(2):are
Console(1):records
Console(2):from
Console(1):input
Console(2):1
MyTest 	dispatch records from secondary input stream to primary and secondary output stream
MyTest 	...first record to primary output, second to secondary output, third to primary, ...
Console(1):secondary
Console(2):inputstream
Console(1):records2
MyTest 	ending...

Stage: LITERAL


Syntax

 
 >>-- LITERAL ---.------------.-----------------------------------------------------><
                 '-- string --'
 
 
 

Purpose

 
 Use the LITERAL stage command to write a specified character string as a
 record to its primary output stream, if it is connected.  If the primary input
 stream for the LITERAL stage contains any records, LITERAL then copies the
 records from its primary input stream to its primary output stream.
 
 

Operands

 
 string
     is a string of characters that make up a record.  The string begins
     exactly one space after the LITERAL stage command and ends with the last
     character before the stage separator (!), the pipeline end character or
     the end of the pipeline.  It includes any leading or trailing blanks.  If
     you do not specify string, LITERAL creates a null record.

Streams

 
 PRIMARY INPUT STREAM:  LITERAL reads records from its primary input stream.
 
 PRIMARY OUTPUT STREAM:  After writing string to its primary output stream,
 LITERAL copies any records read from its primary input stream to its primary
 output stream.

Examples

Example 1

The following PIPE command writes a character string to the terminal: pipe "literal This is a record.! console" This is a record. Results
                                               
pipe "literal This is a record.! console" 
This is a record.

Stage: MQSERIES


Syntax

 
 
                       .--- Browse ---.
  >>----- MQseries ----+--------------+------| definitions |--------------><
                       |--- Get ------|
                       |--- Put ------|
                       '--- Size -----'
 
  definitions: 
 
          <-------------------------------<
  >>-----.---------------------------------.------------------------------><
         |----- Host --------- hostname ---|
         |----- Port --------- port -------|
         |--.-- QMgr ------.-- qmanager ---|
         |  '-- QManager --'               |
         |----- Channel ------ channel ----|
         '----- Queue -------- queue ------'
 

Purpose

 
 Use the MQSERIES stage command to issue basic MQSeries commands,
 such as Browse, Put, Get, Size to q Queue.
 
 This is a sample drivers to demonstrate the facility for interfacing
 with an external environment.
 

Operands

 host
 		hostname of the MQseries server (hosting the queue manager).

 port
 		port number used by the MQSeries server.
       Default is 1414.

 qmanager
 		name of the queue manager.

 channel
 		name of the server connection channel.
       Default is SYSTEM.AUTO.SVRCONN.

 queue
 		name of the queue to get info.
       Default is SYSTEM.DEFAULT.LOCAL.QUEUE.

Streams

 
 PRIMARY INPUT STREAM:  MQSERIES reads records from its primary input stream
 only if there are no argument with stage or if PUT definition is given.
 
 If MQSERIES stage has no argument, records from primary input stream are 
 considered as stage arguments
 If MQSERIES stage has PUT argument (with associated definitions), records
 are considered as data to be put into the queue.
 
 PRIMARY OUTPUT STREAM:  Results from BROWSE, GET, SIZE commands.

Examples

Example 1

To get size of the TEST queue on system MYHOST running queue manager MYQMGR: pipe "mq size host myhost qm MYQMGR q TEST !cons " To put content of a local file into the TEST queue: pipe "< localfile ! mq put host myhost qm MYQMGR q TEST " To browse content of the TEST queue: (non destructive read) pipe "mq browse host myhost qm MYQMGR q TEST !cons" To get content of the TEST queue: (destructive read) pipe "mq get host myhost qm MYQMGR q TEST !cons"

Example 2

To check size of the queues TEST1, TEST2 and TEST3 defined in the same system MYHOST running queue manager MYQMGR: pipe "literal TEST1 TEST2 TEST3!split!specs /size host myhost qm MYQMGR q/ 1 w1 nw!mq!cons " ¤ literal TEST1 TEST2 TEST3 writes string 'TEST1 TEST2 TEST3' to output stream ¤ split split record into three records ¤ specs /size host myhost qm MYQMGR q/ 1 w1 nw reformat records to create mqseries request for each queue ¤ mq calls MQseries stage to process input stream records ¤ cons displays results to console

Stage: MSGSEND


Stage in development

Syntax

 
 
                      <-------------------------<                                 
  >>----- MSGSEND------.--- -H host ----------.----- addresses -----------------><
                       |--- -S subject -------|
                       |--- -O originator ----|
                       |--- -C copy ----------|
                       |--- -Bcc blindcopy ---|
                       '--- -Debug -----------'
 
 

Purpose

(purpose not available)

Operands

(operands not available)

Streams

 
 PRIMARY INPUT STREAM:  MSGSEND reads records from its primary input stream
 and treat them as message body if addresses have been given in argument.
 If only smtp host has been given in argument, then primary input stream must at least contain
 to be continued....
 PRIMARY OUTPUT STREAM: 

Examples

(examples not available)

Stage: PING


Syntax

(syntax not available)

Purpose

(purpose not available)

Operands

(operands not available)

Streams

(streams not available)

Examples

(examples not available)

Stage: RANGE


Syntax

(syntax not available)

Purpose

(purpose not available)

Operands

(operands not available)

Streams

(streams not available)

Examples

(examples not available)

Stage: REMOTE


Syntax

 
                                  
  >>--.--- STAGECLIent --.-----.-- host ---.-------------- stage ----.------------------.--><
      '--- REMOTE -------'     '-- :port --'                         '--- parameters ---' 
 

Purpose

 
 Use the STAGECLIENT stage command to run a stage remotely.
 The stage will be run on the server in the same way as in local.
 All input/output streams used by the stage are simulated at server level
 and data between client and server are handle by separate sockets
 (Server defines one socket per input/output stream for exchanging data
 with the cllient).
 
 In order to run the stage, STAGECLIENT must connect to the server 
 on which the STAGESERVER stage must running to listen for clients.
 

Operands

 host
 		hostname of the server that will run the stage.

 port
 		port number used by the server.
       Default is 1959.

 stage
 		name of the stage to run remotely.

 parameters
 		parameters for the stage.

Streams

 
 INPUT STREAMs:  Depending on the stage to run, input streams correspond
 to those defined for running the stage.
 
 OUTPUT STREAMs:  Depending on the stage to run, output streams correspond
 to those defined for running the stage.
 

Examples

Example 1

To get all processes running on the AIX system myhost.sma.ibm.com: pipe "stageclient myhost.sma.ibm.com:1959 command ps -ef ! cons " At myhost.sma.ibm.com the stageserver must be up and running: pipe "stageserver " ¤ stageclient myhost.sma.ibm.com:1959 command ps -ef - myhost.sma.ibm.com name of the server to run the stage - :1959 port number (this is the default) - command ps -ef command to run on aix system (ps -ef) ¤ cons displays results to console

Example 2

To dispatch records from a file to two separate machines (M1 and M2). - At M1 run the following: pipe "stageserver 11111" - At M2 run the following: pipe "stageserver 22222" At client run the following: pipe "(end ?) < inputfile ! l:locate /M1/ ! remote M1:11111 > m1.data ? l: ! remote M2:22222 > m2.data " ¤ < inpufile read ecords from inputfile ¤ l:locate /M1/ writes records containing M1 to primary output stream and write other records to stage connected to l: ¤ remote M1:11111 > m1.data connect to server M1 on port 11111 and run stage > m1.data to write records to file m1.data ¤ ? separator of pipelines ¤ l: connector of locate, all records do not match M1 will go here ¤ remote M2:22222 > m2.data connect to server M2 on port 22222 and run stage > m2.data to write records to file m2.data

Stage: STAGECLIENT


Syntax

 
                                  
  >>--.--- STAGECLIent --.-----.-- host ---.-------------- stage ----.------------------.--><
      '--- REMOTE -------'     '-- :port --'                         '--- parameters ---' 
 

Purpose

 
 Use the STAGECLIENT stage command to run a stage remotely.
 The stage will be run on the server in the same way as in local.
 All input/output streams used by the stage are simulated at server level
 and data between client and server are handle by separate sockets
 (Server defines one socket per input/output stream for exchanging data
 with the cllient).
 
 In order to run the stage, STAGECLIENT must connect to the server 
 on which the STAGESERVER stage must running to listen for clients.
 

Operands

 host
 		hostname of the server that will run the stage.

 port
 		port number used by the server.
       Default is 1959.

 stage
 		name of the stage to run remotely.

 parameters
 		parameters for the stage.

Streams

 
 INPUT STREAMs:  Depending on the stage to run, input streams correspond
 to those defined for running the stage.
 
 OUTPUT STREAMs:  Depending on the stage to run, output streams correspond
 to those defined for running the stage.
 

Examples

Example 1

To get all processes running on the AIX system myhost.sma.ibm.com: pipe "stageclient myhost.sma.ibm.com:1959 command ps -ef ! cons " At myhost.sma.ibm.com the stageserver must be up and running: pipe "stageserver " ¤ stageclient myhost.sma.ibm.com:1959 command ps -ef - myhost.sma.ibm.com name of the server to run the stage - :1959 port number (this is the default) - command ps -ef command to run on aix system (ps -ef) ¤ cons displays results to console

Example 2

To dispatch records from a file to two separate machines (M1 and M2). - At M1 run the following: pipe "stageserver 11111" - At M2 run the following: pipe "stageserver 22222" At client run the following: pipe "(end ?) < inputfile ! l:locate /M1/ ! remote M1:11111 > m1.data ? l: ! remote M2:22222 > m2.data " ¤ < inpufile read ecords from inputfile ¤ l:locate /M1/ writes records containing M1 to primary output stream and write other records to stage connected to l: ¤ remote M1:11111 > m1.data connect to server M1 on port 11111 and run stage > m1.data to write records to file m1.data ¤ ? separator of pipelines ¤ l: connector of locate, all records do not match M1 will go here ¤ remote M2:22222 > m2.data connect to server M2 on port 22222 and run stage > m2.data to write records to file m2.data

Stage: STAGESERVER


Syntax

 
                                  
  >>--.--- STAGESERVER --------.----------.--><
                               '-- port --'
 

Purpose

 
 Use the STAGESERVER stage command to activate the server which will
 execute STAGECLIENT requests.
 
 You can define the port you want (0 to 1024 are predefined ports) and 
 check in the services file (on your system) if the port you want to use
 is not used by an application.
 The default port used by STAGESERVER is 1959
 (no award will be given to whom will find why 1959)
 

Operands


 port
 		port number used by the server.
       Default is 1959.


Streams

 
 PRIMARY INPUT STREAM:  n/a at the moment.
 In a next release, you will be able to pass a list of authorized client
 and authorized stage to run.
 
 PRIMARY OUTPUT STREAM:  n/a at the moment.
 In a next release, all connection hits will be writtent to output stream
 

Examples

Example 1

To start server on machine: pipe " stageserver "

Stage: CONSOLE


Syntax

 
If console is not first stage (display to terminal):
 
       >>-- CONSole ----.----------------------------.----><
                        |--- MORE --.-------------.--|
                        |           '--- lines ---'  | 
                        |                            |
                        '----------- number ---------'
 
If console is first stage (read data from terminal):
 
       >>-- CONSole --.----------------------------.------><
                      |-- EOF--.-- /string/ ----.--|  
                      |        |-- Xhexstring --|  |  
                      |        |-- Hhexstring --|  |  
                      |        '-- Bbinstring --'  |  
                      '-- NOEOF--------------------'  
 
 

Purpose

 
 Use the CONSOLE stage command to read lines from or write lines to the
 terminal.
 
 When CONSOLE is the first stage of a pipeline, CONSOLE reads records from the
 terminal and writes the records to its primary output stream if it is
 connected.  CONSOLE stops reading if its output stream is not connected.  If
 no operands are specified, CONSOLE also stops reading when a null line is
 entered.  To enter a null line, press enter without typing anything on the
 command line.
 
 When CONSOLE is not the first stage of a pipeline, CONSOLE reads records from
 its primary input stream and writes them to the terminal and to its primary
 output stream, if it is connected.
 

Operands

 
 EOF
     specifies that CONSOLE is to stop reading from the terminal if the line
     read matches string, hexstring, or binstring.
 
 /(diagonal)
     signifies any nonblank delimiting character that does not appear within
     string.
 
     You cannot use a B, b, X, x, H, or h for a delimiting character.
 
 string
     is a string of characters you want CONSOLE to recognize as a signal to
     stop reading from the terminal.  The string is not written to the output
     stream.  Uppercase and lowercase representations of the same characters do
     not match.  CONSOLE stops reading from the terminal if the line read
     matches the target string you specify.
 
 Xhexstring
 Hhexstring
     is a string of hexadecimal characters, following the X or H, that defines
     a string of characters you want CONSOLE to recognize as a signal to stop
     reading from the terminal.  The string is not written to the output
     stream.  CONSOLE stops reading from the terminal if the line read matches
     the target string you specify.  The X or H can be specified in uppercase
     or lowercase.  You must not specify any spaces in the string.  There must
     be an even number of hexadecimal characters in the string.
 
 Bbinstring
     specifies a string of 0's and 1's, following the B, that defines a string
     of characters you want CONSOLE to recognize as a signal to stop reading
     from the terminal.  The string is not written to the output stream.
     CONSOLE stops reading from the terminal if the line read matches the
     target string you specify.  The B can be specified in uppercase or
     lowercase.  You must not specify any spaces in the string.  The number of
     binary digits must be divisible by 8.
 
 NOEOF
     specifies that CONSOLE should not inspect the input data for a group of
     characters signalling end of file; CONSOLE stops only when it finds that
     its primary output stream is not connected.
 
 MORE
     simulates the Aix,Unix,Linux,Dos MORE function.
     Display nn lines then pause waiting user interaction to continue display.
     (nn is 24 by default)
 
 lines
     Number of lines to display before to pause when MORE function activated.
     Default is 24.
 
 number
     Allow to prefix printed lines with the string 'Console(number):'  
     This is a useful functionality when you test pipeline command
	  having more than one pipeline.
     If the console stage is followed by another stage, the string
     'Console(number):' is not appended to record to output stream
 

Streams

 
 PRIMARY INPUT STREAM:  When CONSOLE is not the first stage of a pipeline,
 CONSOLE reads records from its primary input stream.
 
 PRIMARY OUTPUT STREAM:  When CONSOLE is the first stage of a pipeline, CONSOLE
 writes the records it reads from the terminal to its primary output stream.
 When CONSOLE is not the first stage of a pipeline, CONSOLE writes the records
 it reads from its primary input stream to its primary output stream.

Examples

Example 1

To display the first two lines of your autoexec.bat at your terminal, enter the following: pipe "< c:\autoexec.bat ! take 2 ! console" The < stage reads records from autoexec.bat and writes them to its primary output stream. The TAKE stage reads the records written by the < stage. After 2 records have been read, TAKE disconnects its input stream. Therefore, < reads no more records. The CONSOLE stage writes the records to the terminal.

Example 2

To read user responses from the terminal until the user types that's all folks and to write each line of the response to the file user.answers issue the following: pipe "console eof /that's all folks/ ! > user.answers"

Example 3

Use number argument to distinct output streams on screen... To distinguish records between outputs, you can code as: (end ?)literal laurent bea gerard philippe jean jacques!split!sort!cons!f:frtarget find j!cons 1? f:!cons 2 literal ..... generate first names in one line split make one line for each name sort sort the names cons display them on screen f:frtarget.... write to primary output records from the one beginning with 'j' cons 1 display selected records by prefix them with 'Console(1):' ? new pipeline f: connector for secondary output stream of frtarget cons 2 display unselected records by prefix them with 'Console(2):' and result is as: bea gerard Console(2):bea jacques Console(2):gerard jean Console(1):jacques laurent Console(1):jean philippe Console(1):laurent Console(1):philippe

Stage: FULLSCREEN


Syntax

 
 
 >>-- FULLSCreen ---.-----------------------------------------------.----------------------><
                    '--- police ---.----------------------------.---'
                                   '--- size --.------------.---'
                                               '--- type ---'
 
 

Purpose

 Use the FULLSCREEN instead of CONSOLE if you wish to be able to scroll through records.
 Be careful, there is no limitation in number of records to be appended to the textarea.
 The Defaults about characters typeface is: 'Courier 12 0'

Operands

 
 police
     is the name of character typeface you want to use.
     Default is: Courier
 
 size
     is an integer representing the size of characters to be used.
     Default is: 12
 
 type
     is an integer that can be:
        0  for PLAIN characters
        1  for BOLD characters
        2  for ITALIC characters
 
     (see Java Font class specifications..)

Streams

 PRIMARY INPUT STREAM:   FULLSCREEN reads all records from its primary input 
                         stream and append them to the fullscreen textarea.
 
 PRIMARY OUTPUT STREAM:  FULLSCREEN copies its input records to its primary output
                         stream..
 

Examples

 To 'browse' the entire contents of your autoexec.bat, enter the
 following:
 
   pipe "< c:\autoexec.bat ! fullscreen" 
 
 The < stage reads records from autoexec.bat and writes them to its primary
 output stream.  The FULLSCREEN stage appends records to the graphical area.
 
 

Stage: IMMCMD


Syntax

 
 
 >>-- IMMCMD -- command ----------------------------------------------><
 
 

Purpose

 
 Use the IMMCMD stage command to establish an immediate command handler and to
 wait for the specified immediate command to be entered.  When the immediate
 command is entered, any arguments specified on that command are written to
 IMMCMD's primary output stream. An IMMCMD stage can be used only as
 the first stage of a pipeline.
 

Operands

 
 command
     is the name of an immediate command.  The name is translated to uppercase
     before the command handler is established.

Streams

 
 PRIMARY OUTPUT STREAM:  When the immediate command for which IMMCMD has been
 waiting is entered, IMMCMD writes any arguments specified on the immediate
 command to its primary output stream.
 

Examples

(examples not available)

Stage: MENU3270


Stage in development

Syntax

 
 
  >>----- MENU3270 ---------------><
 

Purpose

 
 Use the MENU3270 stage command to create sample menu
 as we did under CMS...
 
 This is a sample driver that is not complete !!!
 See example for details.

 In summary:
 
 You define a menu in a flat file using ISPF menu structure and its default attributes
 that are the following:
        %	define text in highlight color
        +  define text in normal color
        _  define an input field 
 When a key is pressed, MENU3270 writes a record to one output stream	 
 (primary when Enter key, secondary when PF1, tertiary when PF2, ...)
 containg field names and values separated with the hexa character 00

Operands

(operands not available)

Streams

 
 PRIMARY INPUT STREAM:  MENU3270 reads records from its primary input stream
 that describe the menu to display.
 Records have special syntax you can find in examples.
 
 SECONDARY INPUT STREAM:  MENU3270 reads records from its secondary input stream
 that correspond to fields to be refreshed with values.
 Records are in the form FIELD=value 
 
 
 MENU3270 writes a record to output streams each time user press a key
          in the following manner:
  
     When user press ENTER key, MENU3270 writes to its primary   output stream
     When user press PF1   key, MENU3270 writes to its secondary output stream
     When user press PF2   key, MENU3270 writes to its tertiary  output stream
     etc... 
     When user press PF10  key, MENU3270 writes to its eleventh  output stream
 
 The record written to output stream is a record containing all the fields and their value
 separated by hexa character 00
 (ex: FIELD1=value(00)FILED2=value.....
 
 

Examples

Example 1

Sample menu with two fields name and first name that are displayed to console when ENTER is pressed. Also, if command s entered into command line, it is displayed separately pipe "(end ?)< menu.txt !menu3270!split at 00!f:nfind COMMAND!cons ?f:!specs ws = /command entered:/ 1 w2-* nw!cons" menu.txt as looks like: menu.txt
)body
     This is a sample screen
 
 Enter data below and press %ENTER
 
 Name      :_name                  +
 First Name:_fname                 +
     
     
 =>_command                        +

Example 2

Sample menu as the above, but displaying time on the screen sample screen definitions are: )attr § type(output) color(green) )body This is a sample screen Enter data below and press %ENTER Name :_name + First Name:_fname + TimeStamp §time + =>_command + pipe command to run: (end ?) < menu.txt ! m:menu3270!split 00!cons ? literal +1!dup *!delay!timestamp 16!specs 1.4 1 ,/, n 5.2 n ,/, n 7.2 n 9.2 nw /:/ n 11.2 n /:/ n 13.2 n!specs /TIME=/ 1 1-* n!m: ¤ < menu.txt read lines of screen ¤ m:menu3270 display the menu and define connector m: ¤ split 00 split output on 00 hexa character to get one line per field when enter key pressed ¤ cons display on screen values of fields ¤ ? new pipeline ¤ literal +1 define string '+1' ...use by delay (corresponds to +1 second) ¤ dup * duplicate +1 infinitely ¤ delay waits for 1 second (+1) ¤ timestamp 16 appends date time to record ¤ specs .... reformat record yyyy/mm/dd hh:mm:ss ¤ specs /TIME.. append TIME name before time value generated ¤ m: connect to menu3270 as secondary input... so MENU3270 will receive new date per second and will display on screen

Stage: STEM


Syntax

 
 >>--- STEM --- stem ----------------><
 
 

Purpose

 
 Use the STEM stage command to retrieve or set Java String array
 variables whose names begin with the stem you specify.
 
 When STEM is the first stage of a pipeline, STEM retrieves values of
 variables. For each variable retrieved, STEM writes a separate
 record containing the variable's value to its primary output stream.  By
 default, output records are written beginning with stem 0.  The output records
 are written in ascending order of the numeric index of the variables until
 the length of the array.
 
 When STEM is not the first stage of a pipeline, STEM sets variables.  By
 default, when STEM is used to set variables, it sets one variable for each
 record in its primary input stream.  Variables stem[0] through stem[n], where n is
 the number of records in the primary input stream minus 1, are set to the contents of
 the first through the nth input stream records, respectively. STEM also copies
 its primary input stream records to its primary output stream.
 
 For stem to be used in a java class, you have to define
 the Pipeline object by specifying two arguments:
     - the pipeline command (a string)
     - the java class itself (by this)
 And also you must declare the variable (used in stem) as public, like:
     public String[] line;
 
See examples for coding
 

Operands


 stem
     is the stem of the array variables whose values you want to set or
     retrieve. 
 

Streams

 
 PRIMARY INPUT STREAM:  When STEM is not the first stage of a pipeline, STEM
 reads records from its primary input stream.  Input records must contain the
 values of the variables to be set.
 
 PRIMARY OUTPUT STREAM:  When STEM is the first stage of a pipeline, STEM
 writes records to its primary output stream.  Each record contains the value
 of a variable retrieved by STEM.
 
 When STEM is not the first stage of a pipeline, STEM copies its primary input
 stream records to its primary output stream.
 

Examples

Example 1

To get content of the file autoexec.bat into a java array: String[] line; // line must be declared public to be set by Pipeline!! Pipeline p=new Pipeline("< c:\\autoexec.bat ! stem line",this); p.run(); for (int i=0;i/ 1 1-* n !cons ",this); p.run(); Results are: =>First line =>Second line =>Third line =>Fourth line =>Fifth line

Stage: VAR


Syntax

 
 >>--- VAR --- variable ----------------><
 
 

Purpose

 
 Use the VAR stage command to retrieve or set Java String 
 variable whose name is the one you specify.
 
 When VAR is the first stage of a pipeline, VAR retrieves value of
 variable. For the variable retrieved, VAR writes a 
 record containing the variable's value to its primary output stream.
 
 When VAR is not the first stage of a pipeline, VAR sets variable.  By
 default, when VAR is used to set variable, it sets the variable for each
 record in its primary input stream. Then the variable will contain the last record.
 
 For var to be used in a java class, you have to define
 the Pipeline object by specifying two arguments:
     - the pipeline command (a string)
     - the java class itself (by this)
 And also you must declare the variable as public, like:
     public String var;
 
See examples for coding
 

Operands


 variable
     is the variable name you want to set or
     retrieve. 
 

Streams

 
 PRIMARY INPUT STREAM:  When VAR is not the first stage of a pipeline, VAR
 reads records from its primary input stream.  Input records must contain the
 values of the variable to be set.
 
 PRIMARY OUTPUT STREAM:  When VAR is the first stage of a pipeline, VAR
 writes records to its primary output stream. The record contains the value
 of a variable retrieved by VAR.
 
 When VAR is not the first stage of a pipeline, VAR copies its primary input
 stream records to its primary output stream.
 

Examples

Example 1

To get the number of lines of the file autoexec.bat into a java String: public String count; // count must be declared public to be set by Pipeline!! Pipeline p=new Pipeline("< c:\\autoexec.bat ! count lines ! var count",this); p.run(); System.out.println("number of lines is:"+count);

Example 2

To set content of a String into pipeline : public String data="Hello Jojo"; // data must be declared public to be got by Pipeline!! Pipeline p=new Pipeline("var data!specs /=>/ 1 1-* n !cons ",this); p.run(); Results are: =>Hello Jojo

Stage: INSTORE


Syntax

 
 >>--INSTORE--.---------.----------------------------------------------------><
              '-REVERSE-'
 
 

Purpose

 Use the INSTORE stage command to read the records from its input stream into
 storage.  INSTORE writes to its output stream (if it is connected) a 
 record that contains the hashcode of the record that have been read.
 Subsequently, the single output record from INSTORE can be
 read only by OUTSTORE, which uses it to load the records back into the
 pipeline in the order in which they are listed.
 
 

Operands

 
 REVERSE
     builds the list of hashcodes for the output stream in reverse order.  For
     example, the last record read from the input stream is the first one
     described in the output stream.

Streams

 PRIMARY INPUT STREAM:  INSTORE reads records from its primary input stream.
 
 PRIMARY OUTPUT STREAM:  INSTORE writes a record to its primary output
 stream for each records read.  These records contain the hashcode of the
 records read from the input stream.

Examples

Example 1

To read records from autoexec.bat and write them to console in reverse order: pipe "< c:\autoexec.bat!instore reverse!outstore!cons "

Stage: OUTSTORE


Syntax

 
 >>--OUTSTORE----------------------------------------------------><
 
 

Purpose

 Use the OUTSTORE stage command to write to its primary output stream (if it is
 connected) records INSTORE has put in storage.  The primary input stream
 consists of a records which contain hascode of the records in storage.
 

Operands

(operands not available)

Streams

 PRIMARY INPUT STREAM:  OUTSTORE reads a single record from its primary input
 stream.  The record must contain hashcodes to the records to be written.
 The record must be in the same format as an output record from INSTORE.
 
 PRIMARY OUTPUT STREAM:  For each hashcode in the input record, OUTSTORE writes
 to its primary output stream the contents of the record corresponding
 to the hashcode of the object.

Examples

Example 1

To read records from autoexec.bat and write them to console in reverse order: pipe "< c:\autoexec.bat!instore reverse!outstore!cons "

Stage: CHOP


Syntax

 
               .--- 80 -----.
 >>-- CHOP --.-+------------+---------------------------------------------.------><
             | '-- column --'                                             |
             '-.--------------------.--| Group |--.---------.--| Target |-'
               | .-- + --.          |             '-- NOT --'
               '-+-------+-- disp --'
                 '-- - --'
 
 Group:
    .-- BEFORE --.
 |--+------------+-----|
    '-- AFTER ---'
 
 Target:
 |--.-- charrange ------------------.------|
    |-- ANYof --.-- /string/ ----.--|
    |           |-- Xhexstring --|  |
    |           |-- Hhexstring --|  |
    |           '-- Bbinstring --'  |
    '-- STRing --.-- /string/ ----.-'
                 |-- Xhexstring --|
                 |-- Hhexstring --|
                 '-- Bbinstring --'
 
 

Purpose

 Use the CHOP stage command to truncate records selectively.  CHOP reads
 records from its primary input stream, truncates them at the column specified,
 and writes the truncated records to its primary output stream if it is
 connected.  If its secondary output stream is connected, CHOP writes the
 truncated portion of each record to its secondary output stream.  If you do
 not specify an operand, CHOP truncates records after column 80.
 
 Records are truncated relative to occurrences of a specified target.  The
 target can be a range of characters, a list of characters, or a character
 string.
 
 You can specify that the records be truncated at, before, or after a target.
 If you specify that the records are to be truncated before or after the
 target, truncation can occur at a specified displacement before or after the
 target.

Operands

 column
     identifies the column after which CHOP is to truncate the records.
 
 disp
 -disp
     is the relative displacement, in number of columns, from the target to the
     position in the record where truncation is to occur.  If you specify:
 
       o disp and BEFORE, truncation occurs before the column that is disp
         columns to the left of the target
 
       o disp and AFTER, truncation occurs after the column that is disp
         columns to the right of the target
 
       o -disp and BEFORE, truncation occurs before the column that is disp
         columns to the right of the target
 
       o -disp and AFTER, truncation occurs after the column that is disp
         columns to the left of the target.
 
 BEFORE
     causes truncation to take place before the target.  This is the default.
 
 AFTER
     causes truncation to take place after the target.
 
     If you specify AFTER with STRING, the records are truncated after the
     column containing the last character of the first occurrence of string,
     hexstring, or binstring.
 
 NOT
     negates the way in which CHOP locates the target.
 
     If you specify NOT with charrange, the target is any character not within
     that range.  If you specify NOT with ANYOF, the target is any character
     not in the specified list.  If you specify NOT with STRING, the target is
     any column not part of a matching string.
 
 charrange
     is a range of target characters.  CHOP will truncate as specified as soon
     as it finds a character in the input record that matches any character
     within charrange.  You can specify charrange in any of the following ways:
 
     char
     hexchar
         specifies the single character, char, or the 2-character hexadecimal
         representation of a character, hexchar.  Do not enclose the
         hexadecimal representation in quotation marks.
 
     BLANK
     SPACE
         is a single blank character.
 
     char.n
     hexchar.n
     BLANK.n
     SPACE.n
         is a range of n characters beginning with char, hexchar, BLANK, or
         SPACE.
 
     char1-char2
     hexchar1-hexchar2
     hexchar1-char2
     char1-hexchar2
     char1-BLANK
     char1-SPACE
     hexchar1-BLANK
     hexchar1-SPACE
     BLANK-char2
     SPACE-char2
     BLANK-hexchar2
     SPACE-hexchar2
         is a range of characters beginning with char1, hexchar1, BLANK, or
         SPACE and ending with char2, hexchar2, BLANK, or SPACE.
 
     When you specify a range of target characters, the order of characters in
     the range is based on the hexadecimal representation of the characters.
     The characters are arranged in increasing numeric order.  For example, a
     range of 5 characters that begins with A is the range A, B, C, D, and E.
     This corresponds to the hexadecimal representation, X'C1', X'C2', X'C3',
     X'C4', and X'C5'.
 
 ANYof
     specifies that the string of characters following ANYOF is a list of
     target characters.  Truncation occurs when any one of the characters in
     the string is matched.
 
 STRing
     specifies that the string of characters following STRING is a string of
     target characters.  Truncation occurs only when the entire string is
     matched.
 
 /(diagonal)
     signifies any nonblank delimiting character that does not appear in
     string.
 
     You cannot use a B, b, X, x, H, or h for a delimiting character.
 
 string
     defines a group of characters to be located.  Uppercase and lowercase
     representations of the same characters do not match.
 
 Xhexstring
 Hhexstring
     specifies a string of hexadecimal characters, following the X or H, that
     defines a group of characters to be located.  The X or H can be specified
     in uppercase or lowercase.  You must not specify any spaces in the string.
     There must be an even number of hexadecimal characters in the string.
 
 Bbinstring
     specifies a string of 0's and 1's, following the B, that defines a group
     of characters to be located.  The B can be specified in uppercase or
     lowercase.  You must not specify any spaces in the string.  The number of
     binary digits must be divisible by 8.

Streams

 PRIMARY INPUT STREAM:  CHOP reads records from its primary input stream.
 
 PRIMARY OUTPUT STREAM:  After truncating the records read from the input
 stream as specified, CHOP writes the resulting records to its primary output
 stream.
 
 SECONDARY OUTPUT STREAM:  If its secondary output stream is connected, CHOP
 writes the truncated portion of each record to its secondary output stream.

Examples

Example 1
 Given the input file input.data shown in Figure 1, use the following PIPE
 commands to display portions of the records in input file input.data.  The
 terminal output from each of the PIPE commands is shown following the command.
 
 input.data
 ===== * * * Top of File * * *
       |...+....1....+....2....+....3....+....4....+....5....+....6....+....7..
 ===== 1234512345
 ===== 5432154321
 ===== * * * End of File * * *
 
 
 Figure 1. CHOP Stage Command Example: Input File Contents
 
   1.   To truncate input records before the column that is 1 column to the
        left of the first occurrence of the character 3, use the following:
 
          pipe " < input.data ! chop 1 before string /3/ ! console" 
          1
          5
 
   2.   To truncate input records after the column that is 2 columns to the
        right of the first occurrence of the character 4, use the following:
 
          pipe " < input.data ! chop 2 after string /4/ ! console " 
          123451
          5432
 
   3.   To truncate input records between the characters 5 and 4 in occurrences
        of the string 54, use the following:
 
          pipe " < input.data ! chop -1 before string /54/ ! console" 
          1234512345
          5
 
   4.   To truncate input records between the characters 2 and 3 in occurrences
        of the string 123, use the following:
 
          pipe " < input.data ! chop -1 after string /123/ ! console "
          12
          5432154321
 

Stage: JOINCONT


Syntax

 
                              .-- TRAILING --.
 >>-- JOINCONT --.---------.--+--------------+--.-- /string1/ ----.--.-----------------.----><
                 '-- NOT --'  '-- LEADING ---'  |-- Xhexstring1 --|  |-- /string2/ ----|
                                                |-- Hhexstring1 --|  |-- Xhexstring2 --|
                                                '-- Bbinstring1 --'  |-- Hhexstring2 --|
                                                                     '-- Bbinstring2 --'
 
 

Purpose

 
 Use the JOINCONT stage command to join records that are marked with a
 continuation string at the end of the first record or at the beginning of the
 second record.  JOINCONT deletes the continuation string, but you can specify
 another string to be inserted between joined records.
 
 JOINCONT reads records from its primary input stream and concatenates records
 as long as the specified continuation string is present.  When JOINCONT
 encounters a record without the continuation string, it writes the data it has
 concatenated thus far as a record to its output stream and then goes on to
 read its next input stream record.
 

Operands

 
 NOT
     specifies that the records are joined when the specified string1,
     hexstring1, or binstring1 is absent.
 
 TRAILING
     specifies that the continuation string is at the end of the record being
     continued.  TRAILING is the default.
 
     If you specify TRAILING, each input record is inspected for the specified
     trailing string of characters (string1, hexstring1, or binstring1).
 
 LEADING
     specifies that the continuation string is at the beginning of the second
     record being continued.
 
     If you specify LEADING, the next input record is inspected for the
     specified leading string of characters (string1, hexstring1, or
     binstring1).
 
 /(diagonal)
     signifies any nonblank delimiting character that does not appear in the
     string it delimits.
 
     You do not have to use the same delimiter character for string1 and
     string2.
 
     You cannot use a B, b, X, x, H, or h for a delimiting character.
 
 string1
     defines the string of characters as the continuation string.
 
 Xhexstring1
 Hhexstring1
     specifies a string of hexadecimal characters, following the X or H, that
     defines the string of characters as the continuation string.  The X or H
     can be specified in uppercase or lowercase.  You must not specify any
     spaces in the string.  There must be an even number of hexadecimal
     characters in the string.
 
 Bbinstring1
     specifies a string of 0's and 1's, following the B, that defines the
     string of characters as the continuation string.  The B can be specified
     in uppercase or lowercase.  You must not specify any spaces in the string.
     The number of binary digits must be divisible by 8.
 
 string2
     defines the string of characters to replace string1, hexstring1, or
     binstring1 when two records are joined.  When string2 is used with the NOT
     operand, string2 is inserted between the two records being joined.
 
 Xhexstring2
 Hhexstring2
     specifies a string of hexadecimal characters, following the X or H, that
     defines the string of characters to replace string1, hexstring1, or
     binstring1 when two records are joined.  The X or H can be specified in
     uppercase or lowercase.  You must not specify any spaces in the string.
     There must be an even number of hexadecimal characters in the string.
 
 Bbinstring2
     specifies a string of 0's and 1's, following the B, that defines the
     string of characters to replace string1, hexstring1, or binstring1 when
     two records are joined.  The B can be specified in uppercase or lowercase.
     You must not specify any spaces in the string.  The number of binary
     digits must be divisible by 8.

Streams

 
 PRIMARY INPUT STREAM:  JOINCONT reads records from its primary input stream.
 
 PRIMARY OUTPUT STREAM:  JOINCONT writes the joined records to its primary
 output stream.

Examples

Example 1

To combine records in a variable-length file that end with a comma, use the following PIPE command: pipe "< INPUT.FILE ! strip ! joincont /,/ / / ! console " This is the first sentence. This is the second sentence. Note that you need to use the STRIP stage command to delete any trailing blanks. INPUT.FILE
This,
is,
the,
first,
sentence.
This,
is,
the,
second,
sentence.
Results
                                               
pipe "< INPUT.FILE ! strip ! joincont /,/ / / ! console " 
This is the first sentence.
This is the second sentence.

Example 2

To join records that do not end with a period, use the following PIPE command with the data from INPUT.FILE: pipe "< INPUT.FILE ! strip ! joincont not /./ ! console" This,is,the,first,sentence. This,is,the,second,sentence. Results
                                               
pipe "< INPUT.FILE ! strip ! joincont not /./ ! console" 
This,is,the,first,sentence.
This,is,the,second,sentence.

Stage: JOIN4SPLIT


Syntax

(syntax not available)

Purpose

(purpose not available)

Operands

(operands not available)

Streams

(streams not available)

Examples

(examples not available)

Stage: JOIN


Syntax

             .-- 1 -----------------------------------------------------.
 >>-- JOIN --+----------------------------------------------------------+------------------><
             '--.--.-- * --.--.----------------.--.--.---------------.--'
                |  '-- n --'  |-- /string/ ----|  |  '-- maxlength --'
                |             |-- Xhexstring --|  |
                |             |-- Hhexstring --|  |
                |             '-- Bbinstring --'  |
                |  .-- 1 --.                      |
                '--+-------+--.-- /string/ ----.--'
                   |-- * --|  |-- Xhexstring --|
                   '-- n --'  |-- Hhexstring --|
                              '-- Bbinstring --'
 
 

Purpose

 
 Use the JOIN stage command to concatenate one or more input records into a
 single output record.  JOIN reads records from its primary input stream,
 concatenates the records, and writes the concatenated records to its primary
 output stream, if it is connected.  Records are concatenated in the order in
 which they appear in the primary input stream.
 

Operands

 
 n
     specifies the additional number of input records to join to the first
     record.  That is, it concatenates the first n+1 records into a single
     record up to the maxlength if specified.  It then concatenates the next
     n+1 records up to the maxlength if specified.  This process continues
     until all primary input stream records are processed.  If the number of
     records in the input stream is not evenly divisible by n+1, then the last
     output record written contains the remaining records.  If you do not
     specify n, JOIN concatenates pairs of input records.  If you specify 0 for
     n, JOIN copies all primary input stream records unchanged to its primary
     output stream.
 
 *
     specifies that all records in the input stream are combined into a single
     output record, if maxlength is not specified.
 
     If maxlength is specified, input records are combined into one or more
     output records.
 
 /(diagonal)
     signifies any nonblank delimiting character that does not appear in
     string.  If n is not specified but string is specified and string consists
     of only decimal numbers (0-9), you cannot specify a number as the
     delimiting character.  See Usage Note 3 for an example.
 
     You cannot use a B, b, X, x, H, or h for a delimiting character.
 
 string
     is a string of characters to be inserted between concatenated records.  If
     n is not specified, but string is specified and string consists only of
     decimal numbers (0-9), you cannot specify a number as the delimiting
     character.  See Usage Note 3 for an example.
 
 Xhexstring
 Hhexstring
     specifies a string of hexadecimal characters, following the X or H, that
     defines a string of characters to be inserted between concatenated
     records.  The X or H can be specified in uppercase or lowercase.  You must
     not specify any blanks in the string.  There must be an even number of
     hexadecimal characters in the string.
 
 Bbinstring
     specifies a string of 0's and 1's, following the B, that defines a string
     of characters to be inserted between concatenated records.  The B can be
     specified in uppercase or lowercase.  You must not specify any blanks in
     the string.  The number of binary digits must be divisible by 8.
 
 maxlength
     specifies the maximum length of an output record.  For example, if you
     specify *  and 72 for maxlength, input records are concatenated into one
     or more output records that are not longer than 72 characters.
 
     An input record with a length that is equal to or greater than the
     maxlength specified is written unchanged.
 

Streams

 
 PRIMARY INPUT STREAM:  JOIN reads records from its primary input stream.
 
 PRIMARY OUTPUT STREAM:  After concatenating the records read from its primary
 input stream, JOIN writes the resulting records to its primary output stream.

Examples

Example 1

Given the following file JOIN.DATA , use the following command to produce the output shown in Figure 2: pipe "< JOIN.DATA | join 2 /***/ | console" JOIN.DATA
111
222
333
444
555
666
777
888
Results
                                               
pipe "< JOIN.DATA ! join 2 /***/ ! console" 
111***222***333
444***555***666
777***888

Example 2

To combine all lines of file INPUT.FILE into a single record in file OUTPUT.FILE specify: pipe "< INPUT.FILE ! join * ! > OUTPUT.FILE "

Example 3

To combine all lines of file INPUT.FILE into a paragraph with lines of length 72 in file OUTPUT.FILE, specify: pipe "< INPUT.FILE ! split ! join * / / 72 ! > OUTPUT.FILE" The string operand in this example assures that a blank is inserted between each word in INPUT.FILE.

Stage: SPLIT


Syntax

  
 
 >>-- SPLIT --.------------------.-------------------------------------------->
              '-- MINimum -- n --'
 
    .-- AT -- BLANK ----------------------------------------.
 >--+-------------------------------------------------------+-----------------><
    '--| Group |--.---------.--| Target |--.--------------.-'
                  '-- NOT --'              |           (1)|
                                           '-- numrep ----'
 
 Group:
    .-- AT -----------------------------------.
 |--+-----------------------------------------+-------------------|
    '-.-------------------.---.-- BEFORE --.--'
      '--.-------.-- disp-'   '-- AFTER ---'
         '-- - --'
 
 Target:
    .-- BLANK ---------------------.
 |--+------------------------------+------------------------------------|
    |-- charrange -----------------|
    |-- ANYof--.-- /string/ ----.--|
    |          |-- Xhexstring --|  |
    |          |-- Hhexstring --|  |
    |          '-- Bbinstring --'  |
    '-- STRing--.-- /string/ ----.-'
                |-- Xhexstring --|
                |-- Hhexstring --|
                '-- Bbinstring --'
 
 Note:
 (1)  You must specify Target if you specify numrep.
 

Purpose

 
 Use the SPLIT stage command to split records into multiple records.  SPLIT
 reads records from its primary input stream, splits the records, and writes
 the resulting records to its primary output stream, if it is connected.  If no
 operands are specified, SPLIT divides the records at blank characters and
 discards the blanks.
 
 Records are split relative to occurrences of a specified target.  The target
 can be a range of characters, a list of characters, or a character string.
 
 You can specify the number of characters to skip before SPLIT begins looking
 for the target.  You can also specify that the records be split at, before, or
 after a target.  If you specify that the records are to be split before or
 after the target, the split can be made at a specified displacement before or
 after the target.
 
 

Operands

 MINimum n
     specifies a number of characters (n) that are skipped before SPLIT begins
     searching for the target.  n must be a positive integer.  Thus the
     smallest possible output record is n bytes long.
 
 AT
     causes the input records to be split at the specified target.  The target
     characters are discarded.  AT is the default.
 
 disp
 -disp
     is the relative displacement, in number of columns, from the target to the
     position in the record where the split is made.  If you specify:
 
       o disp and BEFORE, a split occurs before the column that is disp columns
         to the left of the target
 
       o disp and AFTER, a split occurs after the column that is disp columns
         to the right of the target
 
       o -disp and BEFORE, a split occurs before the column that is disp
         columns to the right of the target
 
       o -disp and AFTER, a split occurs after the column that is disp columns
         to the left of the target.
 
 BEFORE
     causes input records to be split before the target.  The target characters
     are retained.
 
 AFTER
     causes input records to be split after the target.  The target characters
     are retained.
 
     If you specify AFTER with STRING, the records are split after any columns
     that contain the last character of string.
 
 NOT
     negates the way in which SPLIT locates the target.
 
     If you specify NOT with charrange, the target is any character not within
     that range.  If you specify NOT with ANYOF, the target is any character
     not in the specified list.  If you specify NOT with STRING, the target is
     any column not part of a matching string.
 
 charrange
     is a range of target characters.  If you do not specify charrange, ANYOF,
     or STRING, the default target is a character string consisting of a single
     blank.  You can specify charrange in any of the following ways:
 
     char
     hexchar
         specifies the single character, char, or the 2-character hexadecimal
         representation of a character, hexchar.  Do not enclose the
         hexadecimal representation in quotation marks.
 
     BLANK
     SPACE
         is a single blank character.
 
     char.n
     hexchar.n
     BLANK.n
     SPACE.n
         is a range of n characters beginning with char, hexchar, BLANK, or
         SPACE.
 
     char1-char2
     hexchar1-hexchar2
     hexchar1-char2
     char1-hexchar2
     char1-BLANK
     char1-SPACE
     hexchar1-BLANK
     hexchar1-SPACE
     BLANK-char2
     SPACE-char2
     BLANK-hexchar2
     SPACE-hexchar2
         is a range of characters beginning with char1, hexchar1, BLANK, or
         SPACE and ending with char2, hexchar2, BLANK, or SPACE.
 
     When you specify a range of target characters, the order of characters in
     the range is based on the hexadecimal representation of the characters.
     The characters are arranged in increasing numeric order.
 
 ANYof
     specifies that the string of characters following ANYOF is a list of
     target characters.  A split occurs when any one of the characters in the
     string is matched.
 
 STRing
     specifies that the string of characters following STRING is a string of
     target characters.  A split occurs only when the entire string is matched.
 
 /(diagonal)
     signifies any nonblank delimiting character that does not appear in
     string.
 
     You cannot use a B, b, X, x, H, or h for a delimiting character.
 
 string
     defines a group of characters to be located.  Uppercase and lowercase
     representations of the same characters do not match.
 
 Xhexstring
 Hhexstring
     specifies a string of hexadecimal characters, following the X or H, that
     defines a string of characters to be located.  The X or H can be specified
     in uppercase or lowercase.  You must not specify any spaces in the string.
     There must be an even number of hexadecimal characters in the string.
 
 Bbinstring
     specifies a string of 0's and 1's, following the B, that defines a string
     of characters to be located.  The B can be specified in uppercase or
     lowercase.  You must not specify any spaces in the string.  The number of
     binary digits must be divisible by 8.
 
 numrep
     specifies the maximum number of times each record is split.  For example,
     if you specify a numrep of 2, only the first two occurrences of the target
     in each record cause a split.  Thus, there will be at most three output
     records.  If numrep is not specified, every occurrence of a target causes
     a split.  If you specify numrep without specifying any target character,
     the number you specify as numrep is interpreted as the charrange operand.
     Thus, if you want the default target character, you must specify the BLANK
     operand before numrep.

Streams

 
 
 PRIMARY INPUT STREAM:  SPLIT reads records from its primary input stream.
 
 PRIMARY OUTPUT STREAM:  After splitting the input records into multiple
 records, SPLIT writes the resulting records to its primary output stream.
 
 

Examples

Example 1

To split a list of words into multi lines: pipe "literal this is a list of words!split!cons" Results are: this is a list of words

Example 2

To split a text (from a file) at comma and dot: pipe "< texte.txt!split at anyof /,./ !cons "

Stage: STRIP


Syntax

  
 
 >>-- STRIP --------------------------------------------->
 

Purpose

 
 Use the STRIP stage command to remove leading and trailing blanks from records.
 
 

Operands

(operands not available)

Streams

 
 
 PRIMARY INPUT STREAM:  STRIP reads records from its primary input stream.
 
 PRIMARY OUTPUT STREAM:  After removing leading and trailing balnks from input records
 records, STRIP writes the resulting records to its primary output stream.
 
 

Examples

Example 1

To remove blanks from reocrds: pipe "literal Hello jo !strip!cons" Results are: Hello jo

Stage: CALCULATE


Syntax

 
 >>-- CALCULATE --.---------.---.----------------.------><
                  '-- INT --'   '-- expression --'        
 
 expression:
 
      <---- ; -----<        
 >--.---- statement ----.--><  
    '-- ( statement ) --'  
 
 
 statement:
 
 >--.--- statement --.-- + --.--.-- statement --.---><  
    |                |-- - --|  |               |       
    |                |-- * --|  |               |       
    |                '-- / --'  |               |       
    |---- var --------- = ------'               |       
    |                                           |       
    |---------- numeric_value ------------------|       
    |-------------- Wn -------------------------|       
    '---------- builtin( statement ) -----------'       
 
 Wn   represents the n th word of input record.
 
 builtin is one of:
 
    ABS(x)             -> Absolute value
    ACOS(x)            -> Arc cosine of an angle
    ARRANGement(n,p)   -> Statistical arrangements: n! / (n-p)!
    ASIN(x)            -> Arc sine of an angle
    ATAN(x)            -> Arc tangent of an angle
    ATAN2(a,b)         -> Convert rectangular coordinates (b,a) to polar (r,theta)
    AVG(x,y,z,t,...)   -> Returns average of list of values
    CEIL(x)            -> smallest value
    COMBinaison(n,p)   -> Statistical combinaisons: n! / p! * (n-p)!
    COS(x)             -> Cosine of an angle
    DEB2RAG(x)         -> Convert Degree to Radian
    EXP(x)             -> Exponential number e raised to the power of x
    FACT(x)            -> Factorial of x
    FLOOR(x)           -> largest value
    LN(x)              -> Neperian (natural) logarithm of x
    LOG(x)             -> Base 10 logarithm of x
    MAX(x,y,z,t,...)   -> Maximum value
    MIN(x,y,z,t,...)   -> Minimum value
    MOD(x,y)           -> IEERemainder 
    POWER(x,y)         -> Value of x raised to the power of y
    PROD(x,y,z,t,...)  -> Product of list of values
    RANDOM()           -> Returns a random value
    REMAINDER(x,y)     -> IEERemainder 
    RINT(x)            -> closest value to x
    ROUND(x)           -> closest value to x
    SIN(x)             -> Sine of an angle
    SQRT(x)            -> square root of x
    SUM(x,y,z,t,...)   -> Sum of list of values
    TAN(x)             -> tangent of angle x
 

Purpose

 Use the CALCULATE stage command to evaluate numeric expressions. 
 
 If CALCULATE is the first stage, then the expression is evaluated as is.
 
 If CALCULATE is not the first stage, then:
    * If CALCULATE has no expression in parameter, then the input record
      is considered as the expression to be evaluated.
    * If CALCULATE has an expression in parameter, then the input recocd
      is splitted into words that represent the variables W1, W2, ...
      that can be referenced into the expression.
 
 All the results of expression evaluations are written to the primary output stream.
 
 All values are considered as double.
 If you specify INT as the first CALCULATE parameter, result is returned as integer
 

Operands

 INTeger
     specifies that the result will be return as an integer instead of double.
 
 var
     specifies name of a temporary variable that you use in other statement.
 
 numeric_value
     any numeric value
 
 Wn
     corresponds to the n th word the input record getting from the 
     primaryu input stream.
 

Streams

 PRIMARY INPUT STREAM:  CALCULATE reads records from its primary input stream.
 
 If CALCULATE has an expression in parameter, then words of the input record are put into an hashtable 
 that will correspond to the variables W1, W2,W3, ... in the expression passed with CALCULATE
 
 If CALCULATE has no expression in parameter, then the record is considered as the expression itself.
 
 If CALCULATE is the first stage, then the expression passed in parameter is
 evaluated as is.
 
 PRIMARY OUTPUT STREAM:  After evaluating the expression,
 CALCULATE writes the resulting records to its primary output
 stream.
 

Examples

Example 1

To evaluate 8 raised to the power 2: pipe "calculate power(8,2) ! console" 64.0 to get same but as integer: pipe "calculate int power(8,2) ! console" 64

Example 2

To get the average of notes from the following file: Name Maths Hist Geo English German Physic Bio ------ ------ ----- ---- -------- ------- ------- ---- John 15 8 10 12 13 17 6 James 11 11.5 9 07 14.5 10 8 Liz 10.5 17 16 18 14 09 12 pipe "< notes.txt ! drop 2 ! calculate avg(w2,w3,w4,w5,w6,w7,w8) ! console" Results are 11.571428571428571 10.142857142857142 13.785714285714286 If you want to append name in front of average, then you could use calculate stage in specs stage as a conversion function, like: pipe "< notes.txt!drop 2!specs w1 1 /'s average is: / n w2-* calculate{avg(w1,w2,w3,w4,w5,w6,w7)} nw.5!cons" (in that case, calculate applies on words 2 to * so, in avg() we code w1,w2, ...) Results are: John's average is: 11.57 James's average is: 10.14 Liz's average is: 13.78

Example 3

You can use temporary variables as: pipe " literal 1 2 3 4 5 6!split!calculate toto=toto+w1;toto!cons" Results are: 1.0 3.0 6.0 10.0 15.0 21.0

Stage: LAYOUT


Syntax

 
 >>-- LAYOUT ---.---------------.-----------------------------------------------------><
                '-- separator --'
 
 
 

Purpose

 
 Use the LAYOUT stage to reformat a report with a layout in order to be 
 correctly imported in a spreadsheet.
 LAYOUT replaces the blank separator (field separator) with a character specified
 as parameter (default is ;)
 
  Layout allows to append a specific character after each field
  of a text report having a layout in lines 1 & 2.

  ex:
     consider the first 4 following lines of a report (ie: dsqprint )

     00001 Lastname             Firstname            Age
     00002 -------------------- -------------------- ---
     00003 Doe                  John                  28
     00004 Smith                Alan                  32
     00005 De La RocheFoucault  Antoine Ernest        32

    When you import the type of file in 123 using the text option: layout,
    you can get estonished that 123 didn't correctly fit the columns as you expect.
    It is due to fields containing blanks...
    To be sure for getting a correct matching, you can replace the blank separating fields
    by another character such as comma, semicolon,...

    Layout can do that for you:

    To correctly reformat above file for 123, you can type:
    pipe "< inputfile ! layout ; ! > output.txt" 

    the new content will be:
     00001 Lastname            ;Firstname           ;Age;
     00002 --------------------;--------------------;---;
     00003 Doe                 ;John                ; 28;
     00004 Smith               ;Alan                ; 32;
     00005 De La RocheFoucault ;Antoine Ernest      ; 32;
 

Operands

 
 separator
     is any character to be used as fields separator.
 
     Default is ;

Streams

 
 PRIMARY INPUT STREAM:  LAYOUT reads records from its primary input stream.
 LAYOUT uses the two first records from its primary input stream as layout.
 
 PRIMARY OUTPUT STREAM:  After parsing record, LAYOUT writes it to its primary output stream,

Examples

Example 1

consider the first 4 following lines of a report (ie: dsqprint ) 00001 Lastname Firstname Age 00002 -------------------- -------------------- --- 00003 Doe John 28 00004 Smith Alan 32 00005 De La RocheFoucault Antoine Ernest 32 When you import the type of file in 123 using the text option: layout, you can get estonished that 123 didn't correctly fit the columns as you expect. It is due to fields containing blanks... To be sure for getting a correct matching, you can replace the blank separating fields by another character such as comma, semicolon,... Layout can do that for you: To correctly reformat above file for 123, you can type: pipe "< inputfile ! layout ; ! > output.txt" the new content will be: 00001 Lastname ;Firstname ;Age; 00002 --------------------;--------------------;---; 00003 Doe ;John ; 28; 00004 Smith ;Alan ; 32; 00005 De La RocheFoucault ;Antoine Ernest ; 32; layout.txt
Lastname             Firstname            Age              
-------------------- -------------------- ---               
Doe                  John                  28                
Smith                Alan                  32                 
De La RocheFoucault  Antoine Ernest        32                  
Results
                                               
pipe "< layout.txt ! layout ; ! console " 
Lastname            ;Firstname           ;Age;                   
--------------------;--------------------;---;                    
Doe                 ;John                ; 28;             
Smith               ;Alan                ; 32;              
De La RocheFoucault ;Antoine Ernest      ; 32;               

Stage: PARCEL


Syntax

 
 >>-- PARCEL ------------------------------><
 
 

Purpose

 
 PARCEL treats its primary input stream as a stream of bytes, which is
 parcelled into records of the length specified by numbers read from the
 secondary input stream.
 

Operands

(operands not available)

Streams

 
 PRIMARY INPUT STREAM:  PARCEL reads records from its primary input stream and treat
 them as a stream of bytes, which is parcelled into records of the length
 specified by secondary input stream.
 
 SECONDARY INPUT STREAM:  PARCEL reads records from its secondary input stream and treat
 them as number to parcel primary input records.
 
 PRIMARY OUTPUT STREAM:  PARCEL writes output 
 to its primary output stream.
 

Examples

Example 1

To create a Christmas tree: pipe "(end ?) literal *!dup *!p: parcel!specs 1-* 1.20 center !cons ? literal 1 3 5 7 9 1 1 5!p: " Results are: * *** ***** ******* ********* * * *****

Stage: PARSER


Syntax

 
 >>-- PARSER -----.----------------.---------><
                  '--- template ---'
 
 

Purpose

 
 PARSER is a sample stage to:
 
   * parse records according a template given in parameters
   or
   * parse records according to a rule given in secondary input stream
 
 Template is a list of names, literals or dots in order to parse the data.
 
   ex: parser . '/' unit '/' .   
   if input records are valid IBM Notes Ids, then the parsing will only keep the unit of each one.
 
 Rule is like a BNF definition..see examples:
 
 NOTA: The Parser is used by Pipeline to online parse the pipeline command and stages.

Operands

 
 template
     is a list of names, string enclosed in quotes or dots. 
     See the Rexx parse function for more detail
 

Streams

 
 PRIMARY INPUT STREAM:  PARSER reads records from its primary input stream and 
 try to parse them according to the rules define in parameters or passed in secondary input stream.
 
 SECONDARY INPUT STREAM:  PARSER reads records from its secondary input stream and treat
 them as lines of a (similar) BNF rule.
 If SECONDARY INPUT STREAM is not connected, then parsing is done according to template
 given as parameters (similar to the Rexx syntax of parse function)
 
 PRIMARY OUTPUT STREAM:  PARSER writes records that correspond to the rule or template
 to its primary output stream.
 
 SECONDARY OUTPUT STREAM:  PARSER writes records that do not correspond to the rule or template
 to its secondary output stream.
 

Examples

 Parser allows you to parse data according to rules or parsing in two ways:
 
 1) Parsing in the form of REXX parsing (parse var .... )
 
  	Data coming from input stream 0
 	Tokens defined as arguments of Parser stage
 
 
   ex: parsing Notes IDs, to collect Organisation Units ( France, ...)
 
 	pipe " < inputfile ! parser . '/' unit '/' .  ! cons " 
 
 
  2) Checking that records matchs a specific rule:
 
 		Data coming from input stream 0
 		Rules coming from input stream 1
 
 		Records matching rules go to output stream 0
 		Records that do not match go to output stream 1
 
 	ex: parsing records according to rules (in file ldap.rules):
 
 		<ldap> := <id> : <val> <other>*
 		<id>   := <letter>1n
 		<letter>  := %letter
 	   	<val>  := <car>* 
 		<car>  := %character ^<virg>
 		<virg> := ,
 		<other> := <virg> <id> : <val>
 
 
 		following data into ldap.data
 
 		id:095700
 		dn:Laurent Paris
 		add:Orleans SMA
 		* hhhhhhhh
 		hello dolly:
 
 		pipe "(end ?) < ldap.data !p: parser !cons ? < ldap.rules!p:" 
      
       Results are:
       id:095700
       dn:Laurent Paris
       add:Orleans SMA
 
       In secondary output stream we will get:
 
       * hhhhhhhh
       hello dolly:
 
       That do not match the ldap.rules defined above.
 
  
	
 

Stage: COUNT


Syntax

                                             
 >>-- COUNT --.-------- ALL -------------.-----><
              |                          |    
              |  <-------------------<   |
              '---.-- BYTES -------.-----'
                  |-- CHARS -------|
                  |-- CHARACTErs --|
                  |-- WORDS -------|
                  |-- LINES -------|
                  |-- MINline -----|
                  '-- MAXline -----'
 
 

Purpose

 Use the COUNT stage command to count bytes, blank-delimited character strings,
 or records.  You can also use COUNT to return the length of the shortest or
 longest record.  COUNT reads records from its primary input stream and counts
 each specified item.  If its primary output stream is connected but its
 secondary output stream is not connected, COUNT writes a single record
 containing the count information to its primary output stream and discards the
 records from its primary input stream.  If both its primary and secondary
 output streams are connected, COUNT copies its primary input stream records to
 its primary output stream and writes a single record containing the count
 information to its secondary output stream.
 
 The ALL parameter is a synonym for including all parameters (Bytes,Chars,words,..)
 The output is always in the following order:
 
          characters words lines minimum-record-length maximum-record-length.

Operands

 
 ALL
     is a synonym for all following parameters.
 
 BYTES
 CHARS
 CHARACTErs
     specifies that the number of characters or bytes in the records read from
     the primary input stream is to be included in the count information
     record.
 
 WORDS
     specifies that the number of blank-delimited character strings in the
     records read from the primary input stream is to be included in the count
     information record.
 
 LINES
     specifies that the number of records read from the primary input stream is
     to be included in the count information record.
 
 MINline
     specifies that the length of the shortest record read from the primary
     input stream is to be included in the count information record.  When
     there are no input records, the value is returned as 2(31) - 1.
 
 MAXline
     specifies that the length of the longest record read from the primary
     input stream is to be included in the count information record.  When
     there are no input records, the value is returned as 0.
 

Streams

 PRIMARY INPUT STREAM:  COUNT reads records from its primary input stream.
 
 PRIMARY OUTPUT STREAM:  If its secondary output stream is not connected, COUNT
 writes a single record containing the count information to its primary output
 stream.  If its secondary output stream is connected, COUNT copies its primary
 input stream records to its primary output stream.
 
 SECONDARY OUTPUT STREAM:  If its secondary output stream is connected, COUNT
 writes a single record containing the count information to its secondary
 output stream.
 

Examples

Example 1
    To count lines in autoexec.bat file:
  
    pipe "< c:\autoexec.bat!count lines!cons" 
  
Example 2
    To create a file 'toto' containing the file 'autoexec.bat' with 
    at the first line, number of chars, words and lines.
 
    pipe "(end ?)< c:\autoexec.bat ! c:count all!literal Dummy!w: > toto ? c:!specs /Cars=/ 1 w1 n /Words=/ nw w2 n /Lines=/ nw w3 n!w:" 
  
    the file 'toto' looks like:
    ===== * * * Top of File * * *
    ===== Cars=1071 Words=42 Lines=19
    ===== SET PATH=C:\WINDOWS;C:\WINDOWS\COMMAND;C:\WNE......
    ===== lh keyb fr,,c:\windows\command\keyboard.sys
    ===== @C:\PROGRA~1\NORTON~1\NAVDX.EXE /Startup
	 ===== cls
    ===== .....
    ===== * * * End of File * * *
 

Stage: DUPLICATE


Syntax

 
 
                  .-- 1 --.
 >>-- DUPlicate --+-------+---------------><
                  |-- n --|
                  |-- * --|
                  '-- 1 --'
 

Purpose

 Use the DUPLICATE stage command to write each input record in addition to the
 specified number of copies of each input record.  DUPLICATE reads records from
 its primary input stream and writes records to its primary output stream, if
 it is connected.  It does not discard null input records.

Operands

 
 n
     is the additional number of copies of each input record.  A positive
     number or 0 must be specified for n which causes DUPLICATE to write the
     original record to its output stream.  If you do not specify n, DUPLICATE
     writes one additional copy of each record.
 
 *
     specifies an infinite number of copies of the input.  When you specify
     DUPLICATE *, the first input record is the only one duplicated because it
     is the only one ever read.
 
 -1
     specifies that all input records are consumed and no output is written to
     the output stream.

Streams

 
 PRIMARY INPUT STREAM:  DUPLICATE reads records from its primary input stream.
 
 PRIMARY OUTPUT STREAM:   DUPLICATE writes to its primary output stream the
 original record plus the specified number of copies of each record read from
 its input stream.
 

Examples

 

Example 1

To have 5 rows containing the string 'Hello World' pipe "literal Hello World!dup 4!cons"

Example 2

To start 3 times the calc.exe (Windows calculator) every 15 seconds: pipe "(end ?) literal +15 calc.exe!dup 2!delay!specs w2-* 1!command" ¤ literal +15 calc.exe create the string '+15 calc.exe' into pipeline ¤ dup 2 duplicate two times the record ¤ delay wait for 15 seconds ( see delay stage) ¤ specs w2-* 1 suppress the first word (remains: calc.exe ) ¤ command pass string to operating system. that starts the windows calculator. Warning: as the 'command' stage waits for completion of the command it is executing, you will see the next calculator window after closing the previous one... You can replace 'command' with 'daemon' that doesn't wait for cmd completion...

Stage: LCOUNT


Syntax

(syntax not available)

Purpose

(purpose not available)

Operands

(operands not available)

Streams

(streams not available)

Examples

(examples not available)

Stage: REVERSE


Syntax

 
 >>-- REVERSE -------------------------><
 
 

Purpose

 
 Use the REVERSE stage command to reverse the contents of records on a
 character-by-character basis.  The first character of the input record becomes
 the last character of the output record, the second character becomes the
 second-to-last character, and so on.  REVERSE reads records from its primary
 input stream and writes each record in reverse character order to its primary
 output stream.
 

Operands

(operands not available)

Streams

 
 PRIMARY INPUT STREAM:  REVERSE reads records from its primary input stream.
 
 PRIMARY OUTPUT STREAM:  REVERSE writes each record in reverse character order
 to its primary output stream.
 

Examples

Example 1

The following PIPE command reverses the characters in a literal string: pipe "literal Peace on Earth.! reverse ! console" .htraE no ecaeP

Example 2

This example breaks up a single record into multiple records and then reverses the contents of each of those records. pipe "literal abcde fghijk lmnop qrstuv wxyz! split ! reverse ! console" edcba kjihgf ponml vutsrq zyxw

Stage: CHANGE


Syntax

 
                                .----- 1-* -------------------.
 >>-- CHANGE --.-------------.--+-----------------------------+------------->
               |-- ANYcase --|  |-------- columnrange --------|
               '-- CASEANY --'  |                             |
                                |       <-------------<       |
                                '-- ( ----columnrange---- ) --'
 
 >--.-- /string1/string2/ ---------------------.-----.---.------------------><
    |                                          |     '-n-'
    '-.-- /string1/ ----.--.-- /string2/ ----.-'
      |-- Xhexstring1 --|  |-- Xhexstring2 --|
      |-- Hhexstring1 --|  |-- Hhexstring2 --|
      '-- Bbinstring1 --'  '-- Bbinstring2 --'
 
 

Purpose

 Use the CHANGE stage command to replace a string of characters with another
 string of characters of the same or a different length.  CHANGE reads records
 from its primary input stream, replaces any specified strings that are found
 within the specified column range, and then writes the records to its primary
 output stream if it is connected.  If the target string does not appear in an
 input record, CHANGE writes the record unchanged to its secondary output
 stream, if connected, otherwise it writes the record unchanged to its primary
 output stream.
 
 If ANYCASE is not specified, uppercase and lowercase representations of the
 same characters do not match.  A match is found only if the data in the input
 records matches the target string you specify, including blank characters.
 Blank characters contained in the input stream must match the blank characters
 in the target string.

Operands

 ANYcase
 CASEANY
     specifies that the case of letters be preserved in the following manner.
     The characters specified in the target string and in the input string are
     compared in uppercase.  If the target string is found, and contains one or
     more uppercase characters or contains no letters, the string that replaces
     the target string is inserted in the output record without change of case;
     otherwise, an attempt is made to preserve the case of the string being
     replaced.  When the target string contains no uppercase letters and starts
     with one or more lowercase letters, the following rules determine the case
     of the replacement string:
 
       o When the first two characters of the replaced string in the input
         record are both lowercase, the string that replaces the target string
         is used without change.
 
       o When the first two characters of the replaced string in the input
         record are uppercase, the complete replacement string is translated to
         uppercase.
 
       o When the first character of the replaced string in the input record is
         uppercase and the second one is lowercase (or not a letter or the
         string is only one character), the first letter of the string that
         replaces the target string is translated to uppercase.
 
 columnrange
     specifies what input record columns CHANGE searches for string1,
     hexstring1, or binstring1.  If you do not specify columnrange, CHANGE
     searches the entire input record for occurrences of string1, hexstring1,
     or binstring1.  You can specify columnrange as follows:
 
     column
         is a single column number.
 
     column1-column2
         is a range of columns beginning with column number column1 and ending
         with column number column2, inclusive.  column2 must be numerically
         equal to or greater than column1.
 
     column1-*
         is a range of columns beginning with column number column1 and ending
         with the last column of the record, inclusive.
 
     *-column2
         is a range of columns beginning with the first column of the record
         and ending with column number column2, inclusive.
 
     *-*
         is a range of columns beginning with the first column of the record
         and ending with the last column of the record, inclusive.
 
     column1.n
         is a range of n columns beginning with column number column1.  You can
         specify any number from 1 to 2(31) -1 for n.
 
     You can specify up to ten columnrange operands.  If you specify more than
     one, you must place at least one blank between each columnrange you
     specify and you must enclose the set of columnrange operands within
     parentheses.  You must specify columnrange operands in ascending order.
     If you specify more than one columnrange operand, the ranges of columns
     must not overlap.
 
 /(diagonal)
     signifies a nonblank delimiting character that does not appear within
     string1 or string2.  When three delimiters are used, you must specify the
     same delimiting character in each position.  When two separate strings are
     specified, each with two delimiters, a different delimiter must be used
     for each string.  Also, the character used as the delimiter for the first
     string cannot be present in the second string.  For example,
 
       CHANGE /abc/ ?def?
 
     is the same as
 
       CHANGE /abc/def/
 
     If columnrange is not specified and if both string1 and string2 consist of
     only decimal numbers (0-9), you cannot specify a left parenthesis or a
     number as the delimiting character.  See Usage Note 3 for an example.
 
     You cannot use a B, b, X, x, H, h, or ( for a delimiting character.
 
 string1
     is a target string of characters to change.  If you specify a null string
     for string1, CHANGE inserts string2, hexstring2, or binstring2 immediately
     before the first column of the first columnrange operand you specify.
 
     If columnrange is not specified and if both string1 and string2 consist of
     only decimal numbers (0-9), you cannot specify a left parenthesis or a
     number as the delimiting character.  See Usage Note 3 for an example.
 
 Xhexstring1
 Hhexstring1
     specifies a string of hexadecimal characters, following the X or H, that
     defines a target string of characters to change.  The X or H can be
     specified in uppercase or lowercase.  You must not specify any spaces in
     the string.  There must be an even number of hexadecimal characters in the
     string.
 
 Bbinstring1
     specifies a string of binary characters, following the B, that defines a
     target string of characters to change.  The B can be specified in
     uppercase or lowercase.  You must not specify any spaces in the string.
     The number of binary digits must be divisible by 8.
 
 string2
     is the group of characters that is to replace string1, hexstring1, or
     binstring1.  You must specify the trailing delimiter after string2.  If
     you specify a null string for string2, CHANGE deletes occurrences of
     string1, hexstring1, or binstring1 within the range or ranges you specify
     for columnrange.
 
 Xhexstring2
 Hhexstring2
     specifies a string of hexadecimal characters, following the X or H, that
     defines a string of characters that is to replace string1, hexstring1, or
     binstring1 X or H, that defines a target string of characters to change.
     The X or H can be specified in uppercase or lowercase.  You must not
     specify any spaces in the string.  There must be an even number of
     hexadecimal characters in the string.
 
 Bbinstring2
     specifies a string of binary characters, following the B, that defines a
     string of characters that is to replace string1, hexstring1, or binstring1
     The B can be specified in uppercase or lowercase.  You must not specify
     any spaces in the string.  The number of binary digits must be divisible
     by 8.
 
 n
     is the maximum number of occurrences of string1, hexstring1, or binstring1
     to be changed in each input record.  If you do not specify n, all
     occurrences of string1, hexstring1, or binstring1 within the range or
     ranges you specify for columnrange are changed.  If you specify a null
     string for string1, 1 is the default value for n and 1 is the only value
     allowed for n.
 

Streams

 PRIMARY INPUT STREAM:  CHANGE reads records from its primary input stream.
 
 PRIMARY OUTPUT STREAM:  After replacing any specified strings in records read
 from its input stream, CHANGE writes both records that have been changed and
 records that remain unchanged to its primary output stream when no secondary
 output stream is connected.
 
 SECONDARY OUTPUT STREAM:  When the secondary output stream is defined, CHANGE
 writes changed records to its primary output stream and unchanged records to
 its secondary output stream.

Examples

Example 1
 	The following examples of the CHANGE command use the ANYCASE operand and the
 	rules that apply for preserving the case of letters.
 	
  		pipe "literal Mick ! change anycase /mick/mack/ ! console"
  		Mack
 	
 		pipe "literal Mack MacNeill ! change anycase /mac/mc/ ! console"
   	Mck McNeill
 	
   	pipe "literal Mack MacNeill ! change anycase /macn/mcn/ ! console"
   	Mack Mcneill
 	
   	pipe "literal Mack MacNeill ! change anycase /macN/mcN/ ! console"
   	Mack mcNeill
 	
   	pipe "literal Mack MacNeill ! change anycase /Macn/mcn/ ! console"
   	Mack mcneill
 	
   	pipe "literal Mack MacNeill ! change anycase /MacN/McN/ ! console"
   	Mack McNeill
 	
Example 2
	Issue following cmd to append phone prefix:
 
   pipe " literal 712-1234 !change //(315) / ! cons" 
 
   (315) 712-1234
 
   If phone number are in file phone.numbers, then:
 
   pipe " < phone.number ! change //(315) / ! > phone.withprefix " 
 
Example 3
 
 	Figure 3 and Figure 4 show the contents of the input file color.file and the
 	resulting terminal output after you enter the following command:
 
   pipe "< color.file ! change (5.3 13-15) /RED/GREEN/ ! console " 
 
  color.file
 ===== * * * Top of File * * *
 ===== RED RED RED RED RED
 ===== RED RED RED RED RED
 ===== RED RED RED RED RED
 ===== RED RED RED RED RED
 ===== * * * End of File * * *
 
 Figure 3. CHANGE Stage Command Example: Input File Contents
 
   RED GREEN RED GREEN RED
   RED GREEN RED GREEN RED
   RED GREEN RED GREEN RED
   RED GREEN RED GREEN RED
 
 Figure 4. CHANGE Stage Command Example: Command and Terminal Output
 
 Only the second and fourth occurrences of the string RED are changed to GREEN
 because the columnrange operands specify that only data in columns 5-7 and
 13-15 should change.
 
 Note that the change made within each column range is independent of other
 column ranges.  In this example, the change resulting from the occurrence of
 RED in columns 5-7 does not shift the occurrence of RED out of columns 13-15.
 

Stage: SELECT


Syntax

  
                      <--- , --<            
 >>--SELECT------------ field -----------------><
 

Purpose

 
 Use the SELECT to extract specific data from a report like.
 SELECT reads its primary input stream in the following manner:
   - first line corresponds to the column names
   - second line corresponds to the column length
   - other records are the data records
 Then according to the field names given in parameter command, SELECT
 writes to its primary output stream the corresponding data (as SQL)
 (see Examples for detail)
 

Operands


 field
     corresponds to a valid column name.
 

Streams

 
 PRIMARY INPUT STREAM:  SELECT reads the firts record to get column names, then read the
 second record to get length of columns (ex: ---- --------- ------ ) and it processes all the other
 records as data.
 
 PRIMARY OUTPUT STREAM:  SELECT build new record according to field declaration in command and
 writes it to its primary output stream.
 

Examples

Example 1

In this example, we have a report file REPORT.DAT containing addresses and created by SQL. The SELECT stage, allow to only get name and state for each record. The figures show the input file and the result after entering the following PIPE command: pipe "< REPORT.DAT ! select name,state ! console" REPORT.DAT
Name        Address              City           State   
----------- -------------------- -------------- -----------------
John M.     40 Love Court        Douglaston     New York
Arnold P.   350 Yard Drive       Pebble Beach   California
Joe F.      111 Ringside Street  Pittsburgh     Pennsylvania
Earl A.     24 Bowling Lane      Cincinnati     Ohio
Larry B.    3 Point Road         Boston         Massachusetts
Mike S.     20 Shortstop Road    Philadelphia   Pennsylvania
Joe N.      19 Jet Drive         New York       New York
Running the command displays the following output: Results
                                               
pipe "< REPORT.DAT ! select name,state ! console" 
John M.      New York          
Arnold P.    California        
Joe F.       Pennsylvania      
Earl A.      Ohio              
Larry B.     Massachusetts     
Mike S.      Pennsylvania       
Joe N.       New York           

Stage: SPECS


Syntax

  
                                                                            
             .-STOP--ALLEOF-----.     <---------------------------------------<
  >>--SPECs--+------------------+--.----.-| Group |-------------------------.------.--><
             '-STOP-.-ANYEOF-.--'  |    |-READ------------------------------|      |
                    '-n------'     |    |-READSTOP--------------------------|      |
                                   |    |-WRITE-----------------------------|      |
                                   |    |-SELECT----streamnum---------------|      |
                                   |    |                                   |      |
                                   |    |-PAD-.-char----.-------------------|      |
                                   |    |     |-hexchar-|                   |      |
                                   |    |     |-BLANK---|                   |      |
                                   |    |     '-SPACE---'                   |      |
                                   |    '--.-WORDSEParator--.--.-char----.--'      |
                                   |       |-WS-------------|  |-hexchar-|         |
                                   |       |-FIELDSEparator-|  |-BLANK---|         |
                                   |       '-FS-------------'  '-SPACE---'         |
                                   |                                               |
                                   '--------------|If_statement|-------------------'
  
  If_statement:
  |---id--:--| Input |---IF----operand---operator---operand---THEN---| Group |---ENDIF----------------|
  
  
  Group:
  |--| Input |--| Conversion |--| Output |--| Alignment |----------------------|
  
  Input:
             (1)
  |--.-Words-------wnumberrange----------------.-------------------------------|
     |        (1)                              |
     |-Fields-------fnumberrange---------------|
     |-cnumberrange----------------------------|
     |-/string/--------------------------------|
     |-Xhexstring------------------------------|
     |-Hhexstring------------------------------|
     |-Bbinstring------------------------------|
     |       .-FROM--1-------.  .-BY--1-----.  |
     |-RECNO-+---------------+--+-----------+--|
     |       '-FROM--fromnum-'  '-BY--bynum-'  |
     '-TODclock--------------------------------'
  
  Note:
  (1)  Blanks are optional in this position.
  
  
  Conversion:
  |--.-------.--.-----------------------------.---------------------------------------|
     '-STRIP-'  |---C2B-----------------------|
                |---C2D-----------------------|
                |---C2O-----------------------|
                |---C2X-----------------------|
                |---B2C-----------------------|
                |---B2D-----------------------|
                |---B2O-----------------------|
                |---B2X-----------------------|
                |---D2B-----------------------|
                |---D2C-----------------------|
                |---D2O-----------------------|
                |---D2X-----------------------|
                |---X2B-----------------------|
                |---X2C-----------------------|
                |---X2D-----------------------|
                |---X2O-----------------------|
                |---f2t-----------------------|
                |                             |
                '---CALCulate{ expression }---'       (2)
  
  Output:
  |--.-Next-.--------.------------.--------------------------------------------|
     |      |  (1)   |            |
     |      '-----.n-'            |
     |--.-NEXTWord-.--.--------.--|
     |  '-NWord----'  |  (1)   |  |
     |                '-----.n-'  |
     '-columnrange----------------'
  
  Alignment:
  |--.--------.----------------------------------------------------------------|
     |-Left---|
     |-Center-|
     '-Right--'
  
  Notes:
  (1)  Blanks are not allowed here.
  (2)  This conversion mode allows you to perform arithmetic calculations
       on records. for expression detail see the Calculate stage.

Purpose

 
 Use the SPECS stage command to rearrange the contents of records.  SPECS reads
 records from its primary input stream, by default, or from the one or more
 input streams specified by the operands.  SPECS writes records to its primary
 output stream.
 
 SPECS constructs one or more output records on a field-by-field basis.  The
 output fields can come from input record fields (from one or more input
 records), literal values, the record number, or the time-of-day clock.  The
 data may be converted into a different format before it is placed in the
 output record.  The output data can be left-aligned, centered, or
 right-aligned in the output field.
 
 The basic format of the SPECS stage command is:
 
            <----------------------------------------------<
 >>--SPECS----input--.------------.--output--.-----------.-------------------><
                     '-conversion-'          '-alignment-'
 
 
 input       is literal data or the location of data in the input record you
             specify.  For example, you can specify the string ABC or columns 1
             through 5 of the input record.
 
 conversion  is the type of conversion you can specify to change the format of
             the input data.  For example, input records in binary integer
             format can be converted to a printable decimal string.
 
 output      is the location where the data will be placed.  For example, the
             data can begin in column 3 of the output record.
 
 alignment   is the type of alignment you can specify for the data written to
             the primary output stream.  You can specify the output data to be
             left-aligned, centered, or right-aligned.
 
 Other operands allow you to:
 
   o Specify more than one input stream
   o Specify a character to be used for padding
   o Write pieces of multiple input records to a single output record
   o Write multiple output records from a single input record.
 
 The following is an example of a SPECS stage:
 
              ... ! specs 1-* x2c 5 right ! ...
                           |   |  |   |
                           |   |  |   |
                           |   |  |   |
         input  <----------*   |  |   |
                               |  |   |
         conversion  <---------*  |   |
                                  |   |
         output  <----------------*   |
                                      |
         alignment  <-----------------*
 
 
 

Operands

 Note:  The definitions of most of the operands begin with a notation that
 describes if the operand can be used to define input, conversion, output, or
 alignment.  The operands that do not begin with this notation do not fall into
 one of those categories.
 
 STOP ALLEOF
     specifies that SPECS stops processing records when it determines that all
     input streams being used are at end of file.  STOP ALLEOF is the default.
 
 STOP ANYEOF
     specifies that SPECS stops processing records when it encounters the first
     input stream at end of file.
 
 STOP n
     specifies that SPECS stops processing records when the specified number of
     input streams (n) are at end of file, or when all streams used are at end
     of file.
 
 Words
     (input) defines the location of the input data in a record in terms of
     delimited character strings (words).  The WORDSEPARATOR (or WS) operand
     defines the character that delimits words.  For example, the input
     character string in the following PIPE command consists of 4 words that
     are separated by a blank:
 
       pipe "literal abc def ghi jkl ! specs words 2-4 1 ! console "
       def ghi jkl
 
     The operands WORDS 2-4 specify the second, third, and fourth words in the
     string as the input data for the SPECS stage.
 
     A word cannot be null.  If a record begins with one or more delimiters,
     the first word in that record begins in the position immediately following
     the delimiter or delimiters.  Two or more consecutive delimiters are
     equivalent to having one delimiter which means that the next word begins
     in the first position after the delimiters.  The following example shows
     both types of null words:
 
       pipe " literal ?abc?def??ghi?jkl ! specs ws ? words 2-4 1 ! console "
       def??ghi?jkl
 
 Fields
     (input) defines the location of the input data in a record in terms of
     delimited fields.  The FIELDSEPARATOR operand defines the character that
     delimits fields.
 
     In the following example, the input data contains two fields separated by
     a dash (-):
 
 
       pipe "literal ab cd-ef gh !specs fs - field 1 1 field 2 10 !console "
       ab cd    ef gh
 
     The operands FIELD 1 1 specify that the first field, ab cd, is placed in
     column 1 of the output record, and FIELD 2 10 specifies that the second
     field, ef gh, is placed in column 10 of the output record.
 
     A field can be null.  A record that begins with the delimiter has a null
     field as the first field.  Two delimiters without data between them is
     considered a null field.  The following example shows both types of null
     fields:
 
       pipe " literal ?ab?cd??ef! specs fs ? f1 1 f2 2 f3 5 f4 9 f5 14 ! console " 
        ab cd       ef
 
 wnumberrange
 fnumberrange
 cnumberrange
     (input) defines a specified location of the input data as a range of word
     numbers, field numbers, or column numbers.  The location is relative to
     the beginning or the end of the record.  A negative number in the range
     indicates that the range is relative to the end of the record; otherwise,
     the range is relative to the beginning of the record.  You can specify a
     location as follows:
 
     location
     -location
         (input) is a single column number, word number, or field number.
         -location is relative to the end of the record.  The last location in
         the record is -1.
 
     location1-location2
     location1;location2
     -location1;location2
     location1;-location2
     -location1;-location2
         (input) is a range of columns, words, or fields beginning with
         location1 and ending with location2, inclusive.  If you specify both
         locations relative to the beginning of the input record, (that is, you
         use location1 and location2), location2 must be numerically equal to
         or greater than location1.  If you specify both locations relative to
         the end of the input record, (that is, you use -location1 and
         -location2), location2 must be numerically less than or equal to
         location1.  For example, the following PIPE command specifies the last
         eight columns as the input location:
 
           pipe " literal ABCDEFGHIJKLMN! specs -8;-1 1 ! console" 
           GHIJKLMN
 
         If you specified WORDS, the following PIPE command specifies the
         third-from-last word and the second-from-last word as the input
         location:
 
           pipe " literal ABC DEF GHI JKL MNO! specs words -3;-2 1 ! console "
           GHI JKL
 
         If you specified FIELDS, the following PIPE command specifies the
         third-from-last field and the second-from-last field as the input
         location:
 
           pipe "literal ab?cd?ef?gh?ij! specs fs ? fields -3;-2 1 ! console"
           ef?gh
 
         If you specify location1;-location2 or if you specify
         -location1;location2, the position in the record defined by location1
         must occur before the position in the record defined by location2.
         For example, no positions in the input record to SPECS are rearranged
         if you specify -8;6 for an input record that contains 15 columns since
         location1 is positioned after location2 in the record.
 
     location1-*
     location1;*
     -location1;*
         (input) is a range of columns, words, or fields beginning with
         location1 and ending with the last column, word, or field of the
         record, inclusive.
 
     *-location2
     *;location2
     *;-location2
         (input) is a range of columns, words, or fields beginning with the
         first column, word, or field of the record and ending with location2,
         inclusive.
 
     *-*
     *;*
         (input) is a range of columns, words, or fields beginning with the
         first column, word, or field of the record and ending with the last
         column, word, or field of the record, inclusive.
 
     location1.n
         (input) is a range of n columns, words, or fields beginning with
         location1.  You can specify any number from 1 to 2(31) -1 for n.
 
 /(diagonal)
     (input) is a nonblank delimiting character that does not appear within
     string.  You do not have to use the same delimiter character if string is
     specified more than once in a SPECS stage.  For example,
 
        ... ! specs /abc/ 3 ,xyz, 8 ! ...
 
     is the same as
 
        ... ! specs /abc/ 3 /xyz/ 8 ! ...
 
     You cannot use a W, w, B, b, X, x, H, h, F, or f for a delimiting
     character.
 
 string
     (input) specifies a string of characters that defines the input data.  The
     data defined by string is written to the output record.
 
 Xhexstring
 Hhexstring
     (input) specifies a string of hexadecimal characters, following the X or
     H, that defines the input data.  The X or H can be specified in uppercase
     or lowercase.  The data defined by hexstring is written to each output
     record.  You must not specify any spaces in the string.  There must be an
     even number of hexadecimal characters in the string.
 
 Bbinstring
     (input) specifies a string of 0's and 1's, following the B, that defines
     the input data.  The B can be specified in uppercase or lowercase.  The
     data defined by binstring is written to each output record.  You must not
     specify any spaces in the string.  The number of binary digits must be
     divisible by 8.
 
 RECNO
     (input) specifies that the record number of each record (where, by
     default, the first record number is 1, incrementing by 1 for each
     subsequent record) is the input data.  The record number is written to
     each output record.  The record number is a 10-character field.  The
     number is right-aligned with leading blanks.  For example, the two records
     generated by the following PIPE command contain the record number:
 
       pipe "literal ABC ! literal XYZ ! specs recno 1 1-* 12 ! console"
                 1 XYZ
                 2 ABC
 
 FROM fromnum
     specifies the record number for the first record.  The default is FROM 1.
 
     For example, if you specify:
 
        ... ! specs recno from 10 1 1-* 12 ! ...
 
     the first record is record number 10, the second record is 11, and so on.
 
     You can specify fromnum as a negative number.  If it is negative, a
     leading minus sign is inserted in front of the most significant digit in
     the record number.  The minus sign is dropped if the number has 10
     significant digits.
 
 BY bynum
     specifies the increment for the record numbers.  The default is BY 1.
 
     For example, if you specify:
 
        ... ! specs recno from 10 by 2 1 1-* 12 ! ...
 
     the first record is record number 10, the second record is 12, the third
     record is 14, and so on.
 
     You can specify bynum as a negative number.  For example, if you specify:
 
        ... ! specs recno from 100 by -2 1 1-* 12 ! ...
 
     the first record is record number 100, the second record is 98, the third
     record is 96, and so on.
 
     If the record number is negative, a leading minus sign is inserted in
     front of the most significant digit in the record number.  The minus sign
     is dropped if the number has 10 significant digits.
 
 TODclock
     (input) specifies that each input record written to the output stream has
     the hhmmss value of the time-of-day clock that
     was stored when the corresponding set of input records started getting
     processed.  The time-of-day clock is the local time.
 
 
 STRIP
     (conversion) specifies that the input data is stripped of leading and
     trailing blanks before being converted and placed in the output field.
     For example,
 
        ... ! specs 6.8 strip c2x 1 ! ...
 
     removes leading and trailing blanks from the input data and then converts
     it to hexadecimal.
 
 Note:  The following C2x conversions convert data from an internal (binary)
 representation to a format that can be printed or displayed.
 
 C2B
     (conversion) converts input data bytes (character) to binary.  Each byte
     is converted to its 8-character binary equivalent.  For example:
 
       Input    C2B            Output
       ----- -----------  ----------------
          A  converts to  11000001
         13  converts to  1111000111110011
 
 C2D
     (conversion) converts input data to
     a decimal character string.
 
 C2O
     (conversion) converts input data to its octal value.
 
 
 C2X
     (conversion) converts input data from bytes (character) to hexadecimal
     representation.  The output data contains 2 characters (the hexadecimal
     equivalent) for each input byte.  For example:
 
       Input     C2X       Output
       -----  -----------  ------
       AB     converts to  C1C2
       23     converts to  F2F3
 
 
 B2C
     (conversion) converts input data from binary to byte (character)
     representation.  For example:
 
       Input                        B2C       Output
       -----                     -----------  ------
       1100100010001001          converts to  Hi
       111100011111000011100111  converts to  10X
 
 
 D2C
     (conversion) converts input data to a character representation.
 
 
 f2t
     (conversion) converts input data directly from one printable format f to
     another printable format t.  Table 1 shows the possible values for f
     (From) and t (To).
 
 +----------+--------+---------+--------+---------+--------+
 |          |  To D  |   To X  |  To B  |   To C  |  To O  |
 +----------+--------+---------+--------+---------+--------+
 |  From D  |   --   |   D2X   |   D2B  |   D2C   |  D2O   |
 +----------+--------+---------+--------+---------+--------+
 |  From X  |   X2D  |    --   |   X2B  |   X2C   |  X2O   |
 +----------+--------+---------+--------+---------+--------+
 |  From B  |   B2D  |   B2X   |   --   |   B2C   |  D2O   |
 +----------+--------+---------+--------+---------+--------+
 |  From C  |   C2D  |   C2X   |   C2B  |    --   |  C2O   |
 +----------+--------+---------+--------+---------+--------+
 |  From O  |   O2D  |   O2X   |   O2B  |   O2C   |   --   |
 +----------------------------------------------------------
 
 
 CALCULATE{ xxxxx } 
     allows you apply numeric evaluation against data 
     xxxxx represents the expression tobe evaluated by Calculate.
     For more info about calculate see Calculate stage help.
 
 NEXT
     (output) specifies that the output field begins in the next position in
     the output record.
 
     Specify .n immediately after the NEXT operand to indicate a length (number
     of columns to be used) for the output data.  There cannot be any blanks
     between NEXT and .n.
 
     In the following PIPE command, SPECS writes abc in column one of the
     output record, and then takes the whole record currently in column one
     (pipeline) and places it in the next position in the output field:
 
       pipe "literal pipeline! specs /abc/ 1 1-* next ! console"
       abcpipeline
 
 .n
     (output) specifies the output data length (where n is the number of
     columns) after the operands NEXT, NEXTWORD, or NWORD.  There cannot be any
     blanks between NEXT, NEXTWORD, or NWORD and .n, for example:
 
       pipe "literal Pipelines are! specs 1-* 1 /fun to learn/ next.3 ! console"
       Pipelines arefun
 
 NWord
 NEXTWord
     (output) specifies that the output field is to begin in the column that is
     one after the next available column.  A blank is placed in the next
     available column.
 
     Specify .n immediately after the NEXTWORD or NWORD operand to indicate a
     length for the output data; the length you specify does not include the
     blank that separates the output data.  There cannot be any blanks between
     NEXTWORD or NWORD and .n.
 
     The SPECS stage in the following PIPE command writes its input data,
     Princeton, beginning in the first column of the output record and then
     writes the character string University one space after the next available
     column in the output record:
 
       pipe "literal Princeton! specs 1-* 1 /University/ nextword ! console"
       Princeton University
 
     Specifying NEXTWORD.1, as shown in the following PIPE command, writes the
     first character, U, one space after the next available column in the
     output record:
 
       pipe "literal Princeton! specs 1-* 1 /University/ nextword.1 ! console"
       Princeton U
 
 columnrange
     (output) defines a range of columns that can be used to specify a location
     of the output data.  You can specify columnrange as follows:
 
     column
         (output) is a single column number.
 
 
     column1-column2
         (output) is a range of columns beginning with column number column1
         and ending with column number column2, inclusive.  column2 must be
         numerically equal to or greater than column1.
 
     *-column2
         (output) is a range of columns beginning with the first column of the
         record and ending with column number column2, inclusive.
 
     column1.n
         (output) is a range of n columns beginning with column number column1.
         You can specify any number from 1 to 2(31) - 1 for n.
 
 Left
     (alignment) specifies that the output data is left-aligned within the
     output field.  When there is no conversion of the input data, leading and
     trailing blanks are stripped before alignment.  When the conversion of the
     input data is not D2C, F2C, I2C, P2C, or V2C, the converted data is
     stripped of any leading and trailing blank characters before alignment.
     When the conversion is D2C, F2C, I2C, P2C, or V2C, the converted data is
     not stripped of any leading and trailing blanks before alignment.
 
     If the data is too large for the specified output field, the right-most
     data is truncated to fit the output field.
 
 Center
     (alignment) specifies that the output data is centered within the output
     field.  When there is no conversion of the input data, leading and
     trailing blanks are stripped before centering.  When the conversion of the
     input data is not D2C, F2C, I2C, P2C, or V2C, the converted data is
     stripped of any leading and trailing blank characters before centering.
     When the conversion is D2C, F2C, I2C, P2C, or V2C, the converted data is
     not stripped of any leading and trailing blanks before centering.
 
     If the data is too large for the specified output field, data is truncated
     evenly (when possible) on the left and right to fit the output field.
 
 Right
     (alignment) specifies that the output data is right-aligned within the
     output field.  When there is no conversion of the input data, leading and
     trailing blanks are stripped before alignment.  When the conversion of the
     input data is not D2C, F2C, I2C, P2C, or V2C, the converted data is
     stripped of any leading and trailing blank characters before alignment.
     When the conversion is D2C, F2C, I2C, P2C, or V2C, the converted data is
     not stripped of any leading and trailing blanks before alignment.
 
     If the data is too large for the specified output field, the left-most
     data is truncated to fit the output field.
 
 READ
     consumes the current input record and reads without consuming the next
     record on the currently selected input stream (which is initially the
     primary input stream).  READ can put data from consecutive input records
     into a single output record.  If end of file is encountered when reading
     without consuming an input stream record, input fields referring to any
     part of that record is considered to be null.
 
     The following example shows a SPECS stage that specifies the READ operand:
 
       pipe "literal ABCD! literal 123! specs 1-* 1 read 1-3 4 ! console"
       123ABC
 
     The SPECS stage reads the first record in its input stream and places the
     data (123) in the output record beginning in column 1.  The READ operand
     signals that it is done with that input record.  SPECS then reads the next
     input record and places the first three columns of the data (ABC) in the
     same output record beginning in column 4.
 
     You can use READ if you want to process the output records from the LOOKUP
     stage command to combine a master record and detail record into one
     record.
 
 READSTOP
     consumes the current input record and reads without consuming the next
     record on the currently selected input stream (which is initially the
     primary input stream).  READSTOP can put data from consecutive input
     records into a single output record.  If end of file is encountered when
     reading the file, then SPECS writes the record build so far and does not
     process the remainder of the operands for the stage specified after
     READSTOP.
 
     In the following example, when SPECS processes the last of three records,
     READSTOP writes the record built so far and does not go on to add the
     asterisks to the final output record.
 
       pipe "literal a! dup 2 ! specs 1-* 1 readstop 1-* nw /**/ nw ! console"
       a a **
       a
 
     If you use READ in place of READSTOP in this example, READ continues
     processing the remainder of the stage which adds the asterisks:
 
       pipe "literal a! dup 2 ! specs 1-* 1 read 1-* nw /**/ nw ! console"
       a a **
       a **
 
 WRITE
     writes the output record built so far to the primary output stream.  A
     new, empty output record is begun.  WRITE can put data from a single input
     record into multiple output records.  The following example shows a SPECS
     stage that specifies the WRITE operand:
 
       pipe "literal ABC123! specs 1-3 1 write 4-6 4 ! console"
       ABC
          123
 
     The SPECS stage reads the first 3 columns of the input record and places
     the data (ABC) into the output record beginning in column 1.  WRITE writes
     the record to the output stream.  SPECS then reads the data in columns 4
     through 6 of the same input record and places the data (123) into the next
     output record beginning in column 4.
 
     You can use WRITE if you want to write a record for each word in the input
     record (provided you know there are a fixed number of words).
 
 SELECT
     sets the currently selected input stream.  When SELECT is not specified,
     the primary input stream is the currently selected one.
 
     SPECS reads one record from all input streams specified by the SELECT
     operands for each output record that is built.  SPECS stops when all input
     streams reach end of file.
 
 streamnum
     is the number identifying the input stream to be used as the source for
     the subsequent input data specification, where 0 is the primary input
     stream, 1 is the secondary input stream, and so on.
 
 streamid
     references the input stream to be used as the source for the subsequent
     input data specification, so the stream identifier must match the assigned
     stream name on the label in the pipeline.  For a description of assigning
     a stream name on the PIPE stage command, or the ADDPIPE or CALLPIPE
     subcommands, enter HELP PIPE, HELP PIPE ADDPIPE, or HELP PIPE CALLPIPE.
 
     One record is read from each of the selected input streams for each output
     record that is built.  Input streams that are connected, but not
     referenced, are not read when SELECT is used.
 
     The SPECS stage command stops only when all input streams have reached end
     of file.  Until then, an input stream at end of file is considered to hold
     null records.
 
 PAD
     specifies that a pad character is used to pad the output positions that do
     not contain data after the input data is written to the output location.
     For example, PAD fills positions in front of the output data if you
     specify the data to begin in a column other than the first column or the
     next available column:
 
       pipe "literal 3.14159! specs pad 0 1-* 5 ! console"
       00003.14159
 
     PAD fills positions at the end of the output data if the output data does
     not extend to the last column you specify.  For example:
 
       pipe "literal Why! specs pad ? 1-* 1-10 ! console"
       Why???????
 
     If PAD is specified more than once in a SPECS stage, a pad character
     remains in effect until the next PAD specification is encountered.
 
     A blank is used as the default for PAD.
 
 WORDSEParator
 WS
     specifies the character that is used to separate words in the input
     records.  For example, use WORDSEP to specify that the dash separates each
     word:
 
       pipe "literal a-b-c ! specs wordsep - w1 1 w2 5 w3 9 ! console"
       a   b   c
 
     If WORDSEPARATOR (or WS) is specified more than once in a SPECS stage, a
     word separator character remains in effect until the next WORDSEPARATOR
     (or WS) specification is encountered.
 
     A blank is used as the default for WORDSEPARATOR (or WS).
 
 FIELDSEparator
 FS
     specifies the character that is used to separate fields in the input
     records.  For example, use FIELDSEPARATOR to specify that the question
     mark separates each field:
 
       pipe "literal a?b??c! specs fieldseparator ? f1 1 f2 5 f4 9 ! console"
       a   b   c
 
     If FIELDSEPARATOR (or FS) is specified more than once in a SPECS stage, a
     field separator character remains in effect until the next FIELDSEPARATOR
     (or FS) specification is encountered.
 
     X'05' is the default field separator character.
 
 char
 hexchar
     is the single character, char, or the 2-character hexadecimal
     representation of a character, hexchar.  Do not enclose the hexadecimal
     representation in quotation marks.
 
     Use char or hexchar with:
 
       o PAD to specify the pad character.
 
       o WORDSEPARATOR (or WS) to specify the word separator character.
 
       o FIELDSEPARATOR (or FS) to specify the field separator character.
 
 BLANK
 SPACE
     specifies that blanks are used as the:
 
       o Pad character when specified with the PAD operand.
 
       o Word separator character when specified with the WORDSEPARATOR (or WS)
         operand.
 
       o Field separator character when specified with the FIELDSEPARATOR (or
         FS) operand.
 
  IF,THEN,ENDIF
     specified special criteria selection based on record values
     When the IF condition is true, the group selection after THEN is interpreted
     else nothing is produced.
     Example: to select record having an amount >50 do as: (knowing the amount is the second word in records)
        ....! specs a:w2 if a>50 then 1-* 1 endif ! ....
        This stage defines identifier a for all the second words in records (amount column)
        and for each amount > 50, specs writes the complete record ( 1-* 1 ) 
  
  id
     Define an identifier for the selection that will be used in operands
     Only one letter is allowed (a to z)
 
  operand
     specifies:
        - the identifier defined previously
        - or an integer
        - or a string enclosed with separators
 
  operator
     one of the following:
     =          -> equal to
     ==         -> equal to
     >=         -> greater or equal to
     <=         -> less or equal to
     <>         -> different from
     >          -> greater than
     <          -> less than
     contains   -> contains string
     ncontains  -> do not contain string
 

Streams

 
 INPUT STREAMS:  By default, SPECS reads records from its primary input stream.
 If specified by the operands, SPECS reads records from other specified input
 streams.
 
 PRIMARY OUTPUT STREAM:  After rearranging the contents of the input records as
 specified by the operands, SPECS writes the resulting records to its primary
 output stream.
 

Examples

Example 1

The following command writes the entire input record to the output stream beginning at column 5: pipe "literal The rain!specs 1-* 5!console" The rain The following adds a string to the output record: pipe "literal The rain!specs 1-* 5 /in Spain/ next!console" The rainin Spain For appending a blank between rain and in, use nextword: pipe "literal The rain!specs 1-* 5 /in Spain/ nextword!console" The rain in Spain The following adds an asterisk (using its hexa representation) at column 25: pipe "literal The rain!specs 1-* 5 /in Spain/ nextword x2a 25 !console" The rain in Spain * The following fullfills positions that do not contain data: pipe "literal The rain!specs pad + 1-* 5 /in Spain/ nextword x2a 25 !console" ++++The rain in Spain+++*

Example 2

This example read two files and combine them: pipe "(end ?) < file1!s: specs select 0 read w2 1 /earns / nw select 1 read w3 nw /and is/ nw w2 nw!cons ? < file2 !s:" file1
001111 John  xxxxxx yyyyyy ttttt
001112 James  xxxxxx yyyyyy ttttt
001113 Helen  xxxxxx yyyyyy ttttt
001114 Grant  xxxxxx yyyyyy ttttt
file2
001111 28   15000
001112 35   25000
001113 38   245000
001114 22   11000
Running the command displays the following output: Results
                                               
 pipe "(end ?) < file1!s: specs select 0 read w2 1 /earns / nw select 1 read w3 nw /and is/ nw w2 nw!cons ? < file2 !s:" 
John earns  15000 and is 28
James earns  25000 and is 35
Helen earns  24500 and is 38
Grant earns  11000 and is 22

Example 3

This example selects records having amount greater than 50: pipe "(end ?) < amounts.txt ! specs m:w3 if m>50 then 1-* 1 endif !cons " where: m:w3 save third word in identifier m m>50 condition on the amount 1-* 1 reformat only if previous condition is true amounts.txt
article A              10
article B              20
article C              40
article D              30
article E              10
article F              60
article G              70
Running the command displays the following output: Results
                                               
 pipe "(end ?) < amounts.txt ! specs m:w3 if m>50 then 1-* 1 endif !cons " 
article F              60
article G              70

Stage: XLATE


Syntax



            .-1-*----------------------------------------.
 >>--XLATE--+--------------------------------------------+-------------------->
            !-! Separator !--! Inputrange !--------------!
            !    <----------------------------------<    !
            '-(----! Separator !--! Inputrange !-------)-'

    .-UPper-----------------------------.
 >--+-----------------------------------+------------------------------------><
    '--! Transtable !--! Modifytable !--'

 Separator:
 !--.---------------------------------.---------------------------------------!
    '-.-WORDSEParator--.--.-char----.-'
      !-WS-------------!  !-hexchar-!
      !-FIELDSEparator-!  !-BLANK---!
      '-FS-------------'  '-SPACE---'

 Inputrange:
               
 !--.-Words-------wnumberrange----.-------------------------------------------!
    !                             !
    !-Fields-------fnumberrange---!
    '-cnumberrange----------------'

 Transtable:
 !--.---------------------------------.---------------------------------------!
    ! <-----------------------------< !
    '--.-UPper---------------------.--'
       '-LOwer---------------------'

 Modifytable:
 !--.--------------------------------.----------------------------------------!
    ! <----------------------------< !
    '---fromcharrange--tocharrange---'

 

Purpose

 
 Use the XLATE stage to replace characters according to a translate table.
 XLATE reads records from its primary input stream, compares and replaces
 characters according to the translation specification, and writes the
 resulting records to its primary output stream, if it is connected.  The
 output record has the same length as the input record.

 If its secondary input stream is not connected, and no translate table
 operands or modify table operands are specified, XLATE defines the translate
 table as the uppercase table.  Otherwise, XLATE constructs the translate table
 as follows:

   o If its secondary input stream is not connected, XLATE defines the
     translate table according to the operands.  Each operand specified has a
     cumulative effect on the translate table.  The first translate table
     operand defines the translate table, and any following translate table
     operands modify this translate table, cumulatively.  Then, any
     fromcharrange and tocharrange operands modify the translate table by
     mapping a 'from' character or range of characters to a 'to' character or
     range of characters.  If no translate table is defined in the operands,
     any fromcharrange and tocharrange operands modify the neutral table.

   o If its secondary input stream is connected, XLATE reads the first record
     from its secondary input stream and defines the translate table by the
     first 256 bytes of that record.  If the first record read from its
     secondary input stream is less than 256 bytes, XLATE defines the translate
     table by overlaying the neutral table with the contents of that record
     starting at the first byte of the neutral table.  Any remaining bytes in
     the neutral table are not changed.  The translate table is then modified
	  by any operands, each operand having a cumulative effect.  All translate
     tables operands modify the translate table before any fromcharrange and
     tocharrange operands modify the translate table by mapping a 'from'
     character or range of characters to a 'to' character or range of
     characters.

 You can use XLATE to translate entire records or specified locations of the
 input data in the record.  You can specify locations of the input data in
 terms of columns, words, or fields.  By default, words are defined as
 blank-delimited character strings, and fields are defined as tab-delimited
 character strings.  Input data that is outside all specified locations is left
 unchanged.  When more than one input data location is specified, the contents
 of each location are translated in the order they are specified (left to right
 in the command specification).
 

Operands


 WORDSEParator
 WS
     specifies the character that is used to separate words in the input
     records.  For example, use WORDSEPARATOR to specify that the dash
     separates each word:

       pipe "literal a-b-c ! xlate wordsep - word 3 ! console" 
       a-b-C

     If WORDSEPARATOR (or WS) is specified more than once in an XLATE stage, a
     word separator character remains in effect until the next WORDSEPARATOR
     (or WS) specification is encountered.

     A blank is used as the default for WORDSEPARATOR (or WS).

 FIELDSEparator
 FS
     specifies the character that is used to separate fields in the input
     records.  For example, use FIELDSEPARATOR to specify that the question
     mark separates each field:

       pipe "literal a?b?c ! xlate (fieldsep ? fields 2-3) ! console" 
       a?B?C

    If FIELDSEPARATOR (or FS) is specified more than once in an XLATE stage, a
     field separator character remains in effect until the next FIELDSEPARATOR
     (or FS) specification is encountered.

     X'05' is the default field separator character.

 char
 hexchar
     is the single character, char, or the 2-character hexadecimal
     representation of a character, hexchar.  Do not enclose the hexadecimal
     representation in quotation marks.

     Use char or hexchar with:

       o WORDSEPARATOR (or WS) to specify the word separator character.

       o FIELDSEPARATOR (or FS) to specify the field separator character.

 BLANK
 SPACE
     specifies that a blank is used as the:

       o Word separator character when specified with the WORDSEPARATOR (or WS)
         operand.

  		o Field separator character when specified with the FIELDSEPARATOR (or
         FS) operand.

 Words
     defines the location of the input data in a record in terms of delimited
     character strings (words).  The WORDSEPARATOR (or WS) operand defines the
     character that delimits words.  For example, in the following PIPE
     command, the input character string to XLATE consists of 4 words that are
     separated by a blank:

       pipe "literal abc def ghi jkl ! xlate words 2-4 ! console" 
       abc DEF GHI JKL

     The operands WORDS 2-4 specify the second, third, and fourth words in the
     string as the input data for the XLATE stage.

     A word cannot be null.  If a record begins with one or more delimiters,
     the first word in that record begins in the position immediately following
     the delimiter or delimiters.  Two or more consecutive delimiters are
     equivalent to having one delimiter which means that the next word begins
     in the first position after the delimiters.  In the following example, the
     first word begins after the first delimiter, and the third word begins
     after the two consecutive delimiters:

       pipe "literal ?ab?cd??ef ! xlate (ws ? word 1 word 3) ! console" 
       ?AB?cd??EF

 Fields
     defines the location of the input data in a record in terms of delimited
     fields.  The FIELDSEPARATOR (or FS) operand defines the character that
     delimits fields.

     In the following example, the input data contains three fields separated
     by a dash (-):

       pipe "literal ab cd-ef gh-ij kl ! xlate fieldsep - field 2 ! console" 
       ab cd-EF GH-ij kl

     A field can be null.  A record that begins with the delimiter has a null
     field as the first field.  Two consecutive delimiters is considered a null
     field.  The following example shows both types of null fields.

       pipe "literal ?ab?cd???ef ! xlate (fs ? field 3 field 6) ! console" 
       ?ab?CD???EF

 wnumberrange
 fnumberrange
 cnumberrange
     defines a specified location of the input data as a range of word numbers,
     field numbers, or column numbers which is to be translated.  The location
     is relative to the beginning or the end of the record.  A negative number
     in the range indicates that the range is relative to the end of the
     record; otherwise, the range is relative to the beginning of the record.
     If you do not specify a location, XLATE translates the entire record.  You
     can specify a location as follows:

     location
     -location
         is a single column number, word number, or field number.  -location is
         relative to the end of the record.  The last location in the record is
         -1.

     location1-location2
     location1;location2
     -location1;location2
	  location1;-location2
     -location1;-location2
         is a range of columns, words, or fields beginning with location1 and
         ending with location2, inclusive.  If you specify both locations
         relative to the beginning of the input record, (that is, you use
         location1 and location2), location2 must be numerically equal to or
         greater than location1.  If you specify both locations relative to the
         end of the input record, (that is, you use -location1 and -location2),
         location2 must be numerically less than or equal to location1.  For
         example, the following PIPE command specifies the last eight columns
         as the input location:

           pipe "literal abcdefghijklmn! xlate -8;-1! console" 
           abcdefGHIJKLMN

         If you specified WORDS, the following PIPE command specifies the
         second-from-last and third-from-last words as the input location:

           pipe "literal abc def ghi jkl mno ! xlate words -3;-2 ! console" 
           abc def GHI JKL mno

         If you specified FIELDS, the following PIPE command specifies the
         third-from-last and second-from-last fields as the input location:

           pipe "literal ab?cd?ef?gh?ij! xlate fs ? fields -3;-2 ! console" 
           ab?cd?EF?GH?ij

         If you specify location1;-location2 or if you specify
         -location1;location2, the position in the record defined by location1
         must occur before the position in the record defined by location2.
         For example, no positions in the input record to XLATE are translated
         in the following PIPE command since location1 is positioned after
         location2 in the record:

           pipe "literal abcdefghijklmn! xlate -8;6! console" 
           abcdefghijklmn

     location1-*
     location1;*
     -location1;*
         is a range of columns, words, or fields beginning with location1 and
         ending with the last column, word, or field of the record, inclusive.

     *-location2
     *;location2
     *;-location2
         is a range of columns, words, or fields beginning with the first
         column, word, or field of the record and ending with location2,
         inclusive.

     *-*
     *;*
         is a range of columns, words, or fields beginning with the first
         column, word, or field of the record and ending with the last column,
         word, or field of the record, inclusive.

     location1.n
         is a range of n columns, words, or fields beginning with location1.
         You can specify any number from 1 to 2(31) -1 for n.

 UPper
     specifies that lowercase alphabetic characters are converted to uppercase;
     uppercase letters remain unchanged.  If you do not specify any operands
     for the XLATE stage or if you specify only column ranges, characters in
     the input records are translated to uppercase.

 LOWer
     specifies that uppercase alphabetic characters are converted to lowercase;
     lowercase letters remain unchanged.  If the uppercase translate table
     translated two or more characters to a particular uppercase character,
     when translating from uppercase to lowercase, the character with the lower
     hex value is used.

 fromcharrange tocharrange
     is a pair of characters or character ranges that modifies the translate
     tables.  The character or range of characters specified by fromcharrange
     is converted to the character or range of characters specified by
     tocharrange.  For example, specifying A-B as fromcharrange and 1-2 as
     tocharrange translates A to 1 and B to 2.  The order of characters in the
     range follows the standard collating sequence.  If you specify
     fromcharrange and tocharrange without specifying a translate table, the
     neutral table (no translation at all) is in effect for the characters not
     included in fromcharrange.  You can specify fromcharrange or tocharrange
     in any of the following ways:

     char
     hexchar
         specifies the single character, char, or the 2-character hexadecimal
         representation of a character, hexchar.  Do not enclose the
         hexadecimal representation in quotation marks.

     BLANK
     SPACE
         is a single blank character.

     char.n
     hexchar.n
     BLANK.n
     SPACE.n
         is a range of n characters beginning with char, hexchar, BLANK, or
         SPACE.

     char1-char2
     hexchar1-hexchar2
     hexchar1-char2
     char1-hexchar2
     char1-BLANK
     char1-SPACE
     hexchar1-BLANK
     hexchar1-SPACE
     BLANK-char2
     SPACE-char2
     BLANK-hexchar2
     SPACE-hexchar2
         is a range of characters beginning with char1, hexchar1, BLANK, or
         SPACE and ending with char2, hexchar2, BLANK, or SPACE.

Streams

 
 PRIMARY INPUT STREAM:  XLATE reads records from its primary input stream.

 SECONDARY INPUT STREAM:  XLATE reads the first record from its secondary input
 stream, if it is connected.   The first 256 characters from this record define
 the first translate table used by XLATE.  If the first record read from its
 secondary input stream is less than 256 bytes, XLATE defines the translate
 table by overlaying the neutral table with the contents of the record starting
 at the first byte of the neutral table.  Any remaining bytes in the neutral
 table are not changed.  After this record is read, XLATE severs the secondary
 input stream before processing any records from its primary input stream.

 PRIMARY OUTPUT STREAM:  After translating characters in records read from its
 primary input stream, XLATE writes the resulting records to its primary output
 stream.

Examples

Example 1

In this example, XLATE changes a character string to uppercase: pipe "literal Have a wonderful day.! xlate ! console" HAVE A WONDERFUL DAY. Because the XLATE stage does not specify any operands, the uppercase translate table is used.

Example 2

This example translates three single columns as specified by cnumberrange: pipe "literal BE OBSCURE CLEARLY ! xlate (1 4 12) lower ! console" bE oBSCURE cLEARLY The XLATE stage in the following PIPE command specifies that a lowercase translation takes place in column 2, in a range of 6 columns beginning with column 5, and in a range of columns beginning with column 13 to the end of the character string: pipe "literal BE OBSCURE CLEARLY ! xlate (2 5.6 13-*) lower ! console" Be Obscure Clearly

Example 3

The following PIPE command changes specific characters in a record: pipe "literal (2+2)/10=40%? ! xlate 1-* % . ? 0 4 0 + - ! console" (2-2)/10=00.0 The XLATE stage in the example does the following: o 1-* specifies the cnumberrange from its input stream which includes the entire record o % . specifies fromcharrange and tocharrange where the percent sign (%) is replaced by a period (.) o ? 0 specifies fromcharrange and tocharrange where the question mark (?) is replaced by the number 0 o 4 0 specifies fromcharrange and tocharrange where the number 4 is replaced by the number 0 o + - specifies fromcharrange and tocharrange where the plus sign (+) is replaced by a minus sign (-).

Example 4

When the translation for a given input character is specified more than once, only the last specification is used. For example: pipe "literal abcdefghi ! xlate c-g = e e ! console" ab==e==hi The characters c, d, f, and g are translated to equal signs and e is left as e.

Stage: DEAL


Syntax

 
             .-- STOP --- ALLEOF -----------------------------------.
 >>-- DEAL --+------------------------------------------------------+------><
             |-- STOP ---------.-- ALLEOF --.-----------------------|
             |                 |-- ANYEOF --|                       |
             |                 '-- n -------'                       |
             |                                                      |
             |-- SECONDARY -----------------------------------------|
             |                                                      |
             |                 .-- 1-* --------------------------.  |
             |-- KEY ----------+---------------------------------+--|
             |                 '--| Separator |--| Inputrange |--'  |
             |                                                      |
             |                 .-- 1-* --------------------------.  |
             '-- STREAMID -----+---------------------------------+--'
                               '--| Separator |--| Inputrange |--'
 
 Separator:
 |--.--------------------------------------------.----|
    '--.-- WORDSEParator ---.---.-- char -----.--'
       |-- WS --------------|   |-- hexchar --|
       |-- FIELDSEparator --|   |-- BLANK ----|
       '-- FS --------------'   '-- SPACE ----'
 
 Inputrange:
            (1)
 |--.-- Words ------- wnumberrange ----.-------|
    |        (1)                       |
    |-- Fields ------- fnumberrange ---|
    '-- cnumberrange ------------------'
 
 Note:
 (1)  Blanks are optional in this position.
 
 

Purpose

 Use the DEAL stage command to read records from its primary input stream and
 write records to one of its connected output streams in either sequential
 order starting with the primary output stream, or some other order specified
 on the secondary input stream.  Unless otherwise specified, DEAL writes the
 first input record to the connected primary output stream, the second input
 record to the connected secondary output stream, and so on until the last
 connected output stream receives a record, and then the cycle is repeated.
 
 When the SECONDARY operand is specified, the DEAL stage command sequentially
 processes a secondary input record and a primary input record as a pair.  Each
 secondary input stream record must contain a word that is the output stream
 identifier and that will control the order in which DEAL writes out records.
 In this way you can choose your own output stream order rather than use the
 sequential default.  DEAL first inspects a record from the secondary input
 stream, and retrieves the identity of the output stream that will receive a
 written record.  DEAL then inspects a record from the primary input stream.
 When DEAL determines that the output stream identified in the secondary input
 stream record is connected, DEAL writes a record read from the primary input
 stream to the specified output stream.  DEAL then consumes the records from
 its primary and secondary input streams.
 
 You can also write a contiguous series of primary input stream records that
 have matching keys to the same output stream.  DEAL searches for an identified
 location in each input record that contains the specified key, comparing the
 key from one record to the next.  If the key location is not specified, or is
 specified but is not found, DEAL uses the entire record as the key.

Operands

 
 STOP
     specifies how many output streams must be at end of file for DEAL to stop
     writing input records.  STOP ALLEOF is the default.
 
 ALLEOF
     specifies that input records will stop being written when DEAL determines
     that all output streams are no longer connected.  Input records continue
     to be written as long as at least one output stream is connected.  STOP
     ALLEOF is the default.
 
 ANYEOF
     specifies that input records will stop being written as soon as DEAL
     determines that any one of the output streams is no longer connected.
 
 n
     is the number of streams required to reach end of file and become
     unconnected before DEAL stops writing records.  Specify a decimal number
     of 1 or greater.  Specifying 1 is the same as specifying ANYEOF.
 
 SECONDARY
     specifies that DEAL first inspects a secondary input stream record
     containing a stream identifier before reading its primary input stream
     record and writing it to that identified output stream.  One secondary
     input stream record is processed with one primary input stream record as a
     pair, so the order of the records on the secondary input stream controls
     the order in which DEAL writes primary input stream records to its output
     streams.
 
 KEY
     identifies the location in each input record that contains the key of each
     record.  A contiguous group of input records with the same key are written
     to the same output stream.  When the key changes from one input record to
     the next, DEAL writes the record with the changed key to the next
     sequential, connected output stream.
 
 STREAMID
     specifies that DEAL first inspects the input record for finding the stream identifier
     which will be used to write the record on the accurate output stream.
     STREAMID is a mix of SECONDARY and KEY in that:
       - it uses the inputrange to find stream Id (like KEY)
       - it uses this stream id to write the record on the appropriate output stream (like SECONDARY) 
 
 WORDSEParator
 WS
     specifies the character that is used to separate words in the input
     records.  For example, use WORDSEP to specify that the dash separates each
     word:
     A blank is used as the default for WORDSEParator (or WS).
 
 FIELDSEparator
 FS
     specifies the character that is used to separate fields in the input
     records.  For example, use FIELDSEP to specify that the exclamation mark
     separates each field:
     X'05' is the default field separator character.
 
 char
 hexchar
     is the single character, char, or the 2-character hexadecimal
     representation of a character, hexchar.  Do not enclose the hexadecimal
     representation in quotation marks.
 
     Use char or hexchar with:
 
       o WORDSEParator (or WS) to specify the word separator character.
 
       o FIELDSEparator (or FS) to specify the field separator character.
 
 BLANK
 SPACE
     specifies that a blank is used as the:
 
       o Word separator character when specified with the WORDSEParator (or WS)
         operand.
 
       o Field separator character when specified with the FIELDSEparator (or
         FS) operand.
 
 Words
     specifies, in terms of delimited character strings (words), the input data
     that the DEAL stage command will use as a key.  The WORDSEParator (or WS)
     operand defines the character that delimits words.
 
 Fields
     specifies, in terms of delimited fields, the input data that the DEAL
     stage command will use as a key.  The FIELDSEparator (or FS) operand
     defines the character that delimits fields.
 
 wnumberrange
 fnumberrange
 cnumberrange
     defines a specified location of the input data as a range of word numbers,
     field numbers, or column numbers which DEAL uses to define the key of each
     input record.  The location is relative to the beginning or the end of the
     record.  A negative number in the range indicates that the range is
     relative to the end of the record; otherwise, the range is relative to the
     beginning of the record.  If you do not specify a location, DEAL uses the
     entire input record as the key.  You can specify a location as follows:
 
     location
     -location
         is a single column number, word number, or field number.  -location is
         relative to the end of the record.  The last location in the record is
         -1.
 
     location1-location2
     location1;location2
     -location1;location2
     location1;-location2
     -location1;-location2
         is a range of columns, words, or fields beginning with location1 and
         ending with location2, inclusive.  If you specify both locations
         relative to the beginning of the input record, (that is, you use
         location1 and location2), location2 must be numerically equal to or
         greater than location1.  If you specify both locations relative to the
         end of the input record, (that is, you use -location1 and -location2),
         location2 must be numerically less than or equal to location1.
 
         If you specified WORDS or FIELDS, -2;-1 specifies that the
         second-from-last word or field and the last word or field is the input
         location.
 
         If you specify location1;-location2 or if you specify
         -location1;location2, the position in the record defined by location1
         must occur before the position in the record defined by location2.
         For example, no positions in the input record to DEAL are searched if
         you specify -8;6 for an input record that contains 15 columns since
         location1 is positioned after location2 in the record.
 
     location1-*
     location1;*
     -location1;*
         is a range of columns, words, or fields beginning with location1 and
         ending with the last column, word, or field of the record, inclusive.
 
     *-location2
     *;location2
     *;-location2
         is a range of columns, words, or fields beginning with the first
         column, word, or field of the record and ending with location2,
         inclusive.
 
     *-*
     *;*
         is a range of columns, words, or fields beginning with the first
         column, word, or field of the record and ending with the last column,
         word, or field of the record, inclusive.
 
 
     location1.n
         is a range of n columns, words, or fields beginning with location1.
         You can specify any number from 1 to 2(31) -1 for n.
 

Streams

 
 PRIMARY INPUT STREAM:  DEAL reads records in sequential order from its primary
 input stream.
 
 SECONDARY INPUT STREAM:  DEAL reads a record from its secondary input stream,
 if it is connected and the SECONDARY operand is specified.  The secondary
 input stream record is paired with a primary input stream record.
 
 OUTPUT STREAMS:  DEAL writes each of its primary input stream records to one
 of its connected output streams, in either sequential order starting with the
 primary output stream, or the order specified on the secondary input stream.

Examples

In all the following examples, the pipeline command is defined in a file and 
   run by running pipe command with the -f switch.
 

Example 1

To discard every third input record run the following pipe command which invokes the dealit file: pipe -f dealit +----------------------------------------------------------------------------+ | | | #------------------------ | | # dealit (pipeline file) | | #------------------------ | | (end ?) < input.data # read input file content | | ! d:deal # sequentially write out input records | | ! specs /primary/ 1 1-* nw # nametag primary output stream record | | ! cons # connect to input of stage following caller| | ? # start of second pipeline | | d: # secondary output stream connected | | ! specs /secondary/ 1 1-* nw # nametag secondary output strm recs | | ! console # secondary output stream records to term | | ? # start of third pipeline | | d: # tertiary output stream connected | | ! hole # discard every third record | | | +----------------------------------------------------------------------------+ Note: The records are discarded by the HOLE stage command. Leaving an output stream unconnected in a set of pipelines using the DEAL stage command is not a method of discarding records, it will instead induce an end-of-file condition. Figure 1 is the input file that the DEALIT exec processes. input.data ===== * * * Top of File * * * ===== 0001 Input records ===== 0002 Input records ===== 0003 Input records ===== 0004 Input records ===== 0005 Input records ===== 0006 Input records ===== 0007 Input records ===== 0008 Input records ===== 0009 Input records ===== 0010 Input records ===== 0011 Input records ===== 0012 Input records ===== 0013 Input records ===== 0014 Input records ===== 0015 Input records ===== * * * End of File * * * [linux]$ pipe -f dealit primary 0001 Input records secondary 0002 Input records primary 0004 Input records secondary 0005 Input records primary 0007 Input records secondary 0008 Input records primary 0010 Input records secondary 0011 Input records primary 0013 Input records secondary 0014 Input records

Example 2

The following pipeline reads records from a file on the primary input stream and prepares it for the DEAL stage command. The input file consists of employee information including an identification number, the current salary, the performance level, and the job title. The DEAL stage command uses the level as the comparison key in each input record, and writes records to the primary output stream as long as each record's level matches the level of the first record. When the key of the current record does not match the key of the previous record, the connected secondary output stream is selected to receive the current record. The process continues sequentially through all connected output streams until all records are written. +----------------------------------------------------------------------------+ | | | #------------------- | | # deal | | #------------------- | | (endchar ?) | | < input.data # input records containing employee info | | ! drop 2 # discard the two header records | | ! sort 19.7 # sort input records to order the level | | ! d:deal key words 3 # level is the key in the input record | | ! > PROMOFILE # write record to first output file | | ? # start of second pipeline | | d: # secondary output stream connected | | ! > SALARYPLAN # write record to second output file | | ? # start of third pipeline | | d: # tertiary output stream connected | | ! > NOCHANGEFILE # write record to third output file | | | +----------------------------------------------------------------------------+ o (endchar ?) assigns ? as the pipeline end character. o < input.data reads the file input.data into the pipeline. o drop 2 discards the two header records from the input file. o sort 19.7 sorts the remaining input records in ascending order according to the employee's performance level. Column 19 in each input record contains the level, which is 7 characters in length. o d: deal key words 3 defines a label d for the DEAL stage. The operands on the DEAL stage command identify the third word as the comparison key in each input record. The default word separator is a blank. DEAL writes the first record it reads from its primary input stream to its connected primary output stream. DEAL compares the Level-2 key in the second input record to the Level-1 from the record before, discovers a mismatch, and writes the second input record to its connected secondary output stream. The third record's key matches the second record's key, and is also written to the secondary output stream. When DEAL discovers that the key of the fourth input record does not match Level-2, DEAL writes the fourth input record to its connected tertiary output stream. The fifth input record key of Level-3 matches the key of the fourth, so the fifth record is also written to the tertiary output stream. o > PROMOFILE writes the record that contains Level-1 to the file PROMOFILE on the primary output stream. o ? marks the end of the first pipeline. o d: references the label d on the DEAL stage in the first pipeline and defines the secondary output stream. o > SALARYPLAN writes the records that contain Level-2 to the file SALARYPLAN on the secondary output stream. o ? marks the end of the second pipeline. o d: references the label d on the DEAL stage in the first pipeline and defines the tertiary output stream. o > NOCHANGEFILE writes the remaining input records that contain Level-3 to the file NOCHANGEFILE on the tertiary output stream. inpu.data ===== * * * Top of File * * * |...+....1....+....2....+....3....+....4....+....5....+....6....+....7.. ===== IDENT. SALARY PERF. JOB TITLE ===== ------ ---------- ------- ---------------- ===== 000111 $4,000.00 Level-1 Associate ===== 011234 $12,000.00 Level-2 Staff ===== 096424 $8,000.00 Level-3 Senior Associate ===== 999990 $16,000.00 Level-2 Advisory ===== 111111 $99,000.00 Level-3 Senior ===== * * * End of File * * * PROMOFILE ===== * * * Top of File * * * ===== 000111 $4,000.00 Level-1 Associate ===== * * * End of File * * * SALARYPLAN ===== * * * Top of File * * * ===== 011234 $12,000.00 Level-2 Staff ===== 999990 $16,000.00 Level-2 Advisory ===== * * * End of File * * * NOCHANGEFILE ===== * * * Top of File * * * ===== 096424 $8,000.00 Level-3 Senior Associate ===== 111111 $99,000.00 Level-3 Senior ===== * * * End of File * * *

Stage: FANINANY


Syntax

 
 
 >>--FANINANY----------------------------------------------------------------><
 
 

Purpose

 Use the FANINANY stage command to combine multiple streams into a single
 stream.  FANINANY reads any available input record, regardless of the input
 stream it is on, and copies the records to its primary output stream, if it is
 connected.  Records from a particular input stream appear in the output stream
 in the order in which FANINANY reads them from that input stream, but they may
 be interspersed with records from other input streams.
 

Operands

(operands not available)

Streams

(streams not available)

Examples

 

Example 1

To find records starting with either of two targets, use a FANINANY stage and two FIND stages in a PIPE command. In this example, the original list of users from the 'cat /etc/passwd' command is shown in Figure 2 and the resulting output records from the exec are shown in Figure 3. pipe "(end ?) command cat /etc/passwd!a:find root!f:faninany!cons ? a:!find db2!f:" ¤ (end ?) assigns ? as the pipeline end character. ¤ command cat /etc/passwd issues the cat command on file passwd and writes the response to the pipeline. (can be replaced with: < /etc/passwd ) !!! ¤ a:find root defines a label a for the FIND stage. The FIND stage command writes all records that begin with root to its primary output stream and writes all other records to its secondary output stream (which is defined by the first reference to label a). ¤ f:faninany defines a label f for the FANINANY stage. FANINANY reads the records from its primary and secondary input streams (in the order in which they arrive) and writes them to its primary output stream. ¤ cons writes the records to the terminal. It is the last stage in the first pipeline. ¤ ? marks the end of the first pipeline. ¤ a: references the label a on the FIND stage in the first pipeline and defines the secondary output stream for the FIND stage. The records from the secondary output stream of the FIND stage in the first pipeline flow to the following FIND stage. ¤ find db2 takes the records from the first FIND stage that did not contain 'root' and finds all records that begin with 'db2'. ¤ f: references the label f on the FANINANY stage in the first pipeline and defines the secondary input stream for the FANINANY stage. The records from the previous FIND stage flow to the FANIN stage as its secondary input stream. Figure 1 shows the flow of the records: *---------* *---------* *---------* *--------* |cat /etc/|---->|a: find |------------------->|f: |--->|console | |passwd | | root |--* *->|faninany | | | *---------* *---------* | | *---------* *--------* | | | *---------* | *->| find |-* | db2 | *---------* Figure 2 shows the contents of '/etc/passwd' root:x:0:0:root:/root:/bin/bash bin:x:1:1:bin:/bin: daemon:x:2:2:daemon:/sbin: adm:x:3:4:adm:/var/adm: lp:x:4:7:lp:/var/spool/lpd: sync:x:5:0:sync:/sbin:/bin/sync shutdown:x:6:0:shutdown:/sbin:/sbin/shutdown halt:x:7:0:halt:/sbin:/sbin/halt mail:x:8:12:mail:/var/spool/mail: news:x:9:13:news:/var/spool/news: uucp:x:10:14:uucp:/var/spool/uucp: operator:x:11:0:operator:/root: games:x:12:100:games:/usr/games: gopher:x:13:30:gopher:/usr/lib/gopher-data: ftp:x:14:50:FTP User:/home/ftp: nobody:x:99:99:Nobody:/: xfs:x:100:101:X Font Server:/etc/X11/fs:/bin/false chidlovs:x:500:0:Chris Chidlovsky:/home/chidlovs:/bin/ksh chabanto:x:501:0:Olivier Chabant:/home/chabanto:/bin/ksh db2fenc1:x:502:104::/home/db2fenc1:/bin/bash db2inst1:x:503:103::/home/db2inst1:/bin/bash db2as:x:504:105::/home/db2as:/bin/bash lolo:x:505:0:Laurent Paris:/home/lolo:/bin/ksh niaf:x:506:500:didier niaf:/home/niaf: Figure 3 shows the results root:x:0:0:root:/root:/bin/bash db2fenc1:x:502:104::/home/db2fenc1:/bin/bash db2inst1:x:503:103::/home/db2inst1:/bin/bash db2as:x:504:105::/home/db2as:/bin/bash

Stage: FANIN


Syntax

 
 
 >>-- FANIN --.-----------------.----------------------><
              | <-------------< |
              '--- streamnum ---'
 
 

Purpose

 Use the FANIN stage command to combine multiple input streams into a single
 output stream.  FANIN reads records from all specified input streams and
 copies the records from each input stream to its primary output stream, if it
 is connected.
 
 FANIN, without operands, reads all of the records from its primary input
 stream to its primary output stream, then all of the records from its
 secondary input stream to its primary output stream, and so on, until all of
 its input streams have been processed.  Operands can be specified with FANIN
 to indicate which input streams are read and the order in which they are read.
 

Operands

 
 streamnum
     is a number identifying a particular input stream that FANIN will read,
     where 0 is the primary input stream, 1 is the secondary input stream, and
     so on.
 

Streams

 INPUT STREAMS:   FANIN, without operands, reads all records from all of its
 connected input streams starting with the primary input stream and continuing
 with the rest of the streams in order of increasing stream number.  If one
 streamnum is specified, FANIN reads all the records from only that
 input stream.  If multiple operands are specified, FANIN reads records from
 all the identified streams in the order specified.
 
 FANIN reads all the records from a stream before it begins reading records
 from the next stream.
 
 PRIMARY OUTPUT STREAM:  FANIN copies its input records to its primary output
 stream in the same order it reads the input records.
 

Examples

 

Example 1

In this example, FANIN combines two input streams. The following pipe command combines the files: pipe "(end ?) < DECHOME ! f:fanin ! > DJHOME ? < JANHOME ! f:" ¤ (end ?) assigns ? as the pipeline end character. ¤ < DECHOME reads the file DECHOME into the pipeline. ¤ f: fanin defines a label f for the FANIN stage. FANIN combines multiple streams into a single stream. ¤ > DJHOME writes all the records to the file DJHOME. This is the last stage of the first pipeline. ¤ ? marks the end of the first pipeline. ¤ < JANHOME reads the file JANHOME into the pipeline. ¤ f: references the label f on the FANIN stage of the first pipeline and defines the secondary input stream for the FANIN stage. The records from the previous < stage flow to the FANIN stage as its secondary input stream. The following diagram shows how FANIN merges the files in this example: *-------* | f: | *----------* | | DJHOME FILE A | DECHOME | | F | *------------* | |--------->| | | DECHOME | | | | A | | | | | | | | records | *----------* | N | | | Primary Input Stream | |-------->| - - - - - -| | I | | JANHOME | | | | | *----------* | N | | records | | JANHOME | | | | | | |--------->| | | | | | | | *------------* | | | | Primary Output Stream *----------* | | Secondary Input Stream *-------* DECHOME ===== * * * Top of File * * * ===== December 1990 New Listings ===== 2712 Crescent Drive 56,000 3 Bedroom Ranch ===== 713 Wilson Avenue 98,000 3 Bedroom Split Level ===== 1760 Grand Boulevard 120,000 4 Bedroom 2-Story Colonial ===== * * * End of File * * * JANHOME ===== * * * Top of File * * * ===== January 1991 New Listings ===== 42 Yale Street 55,500 2 Bedroom Cape Cod ===== 2 Sawmill Road 250,000 5 Bedroom Contemporary ===== * * * End of File * * * DJHOME ===== * * * Top of File * * * ===== December 1990 New Listings ===== 2712 Crescent Drive 56,000 3 Bedroom Ranch ===== 713 Wilson Avenue 98,000 3 Bedroom Split Level ===== 1760 Grand Boulevard 120,000 4 Bedroom 2-Story Colonial ===== January 1991 New Listings ===== 42 Yale Street 55,500 2 Bedroom Cape Cod ===== 2 Sawmill Road 250,000 5 Bedroom Contemporary ===== * * * End of File * * *

Example 2

To define four input streams (0, 1, 2, and 3) and combine the streams in a different order, specify the stream numbers in the FANIN stage as in the following exec: pipe "(end ?) < APPLE!a:fanin 3 1 2 0!> FRUITS ? < BANANA !a: ? < CHERRY !a: ? < FIG !a:" ¤ (end ?) assigns ? as the pipeline end character. ¤ < APPLE reads the file APPLE into the pipeline where it becomes the primary input stream (stream 0) for the FANIN stage. ¤ a: fanin 3 1 2 0 defines a label a for the FANIN stage. FANIN combines the input streams in the order 3 1 2 0. ¤ > FRUITS writes all the records to the file FRUITS. It is the last stage of the first pipeline. ¤ ? marks the end of the first pipeline. ¤ < BANANA reads the file BANANA into the pipeline. ¤ a: references the label 'a' on the FANIN stage in the first pipeline and defines the secondary input stream for the FANIN stage. The records from the preceding < stage flow to the FANIN stage as its secondary input stream (stream 1). ¤ ? marks the end of the second pipeline. ¤ < CHERRY reads the file CHERRY into the pipeline. ¤ a: references the label a on the FANIN stage in the first pipeline and defines the tertiary input stream for the FANIN stage. The records from the preceding < stage flow to the FANIN stage as its tertiary input stream (stream 2). ¤ ? marks the end of the third pipeline. ¤ < FIG reads the file FIG into the pipeline. ¤ a: references the label a on the FANIN stage in the first pipeline and defines the quaternary input stream for FANIN stage. The records from the preceding < stage flow to the FANIN stage as its quaternary input stream (stream 3). The following diagram shows the resulting output file FRUITS: FRUITS (Primary Output Stream) *---------------* | | | FIG file | (Records from Input Stream 3) | | | - - - - - - - | | | | BANANA file | (Records from Input Stream 1) | | | - - - - - - - | | | | CHERRY file | (Records from Input Stream 2) | | | - - - - - - - | | | | APPLE file | (Records from Input Stream 0) | | *---------------*

Stage: FANOUT


Syntax

 
 
 >>-- FANOUT --------------------------------------------------><
 
 

Purpose

 Use the FANOUT stage command to make a copy of its input stream on every
 connected output stream.  FANOUT copies records from its primary input stream
 to multiple output streams in the order stream 0, stream 1, stream 2 and so
 on.  FANOUT reads one record at a time from its primary input stream and
 writes each record to all connected output streams.
 

Operands

(operands not available)

Streams

 PRIMARY INPUT STREAM:  FANOUT reads records from its primary input stream.
 
 OUTPUT STREAMS:  FANOUT copies its input records to all of its connected
 output streams starting with the primary output stream and continuing with the
 rest of the streams in order of increasing stream number.
 

Examples

 

Example 1

To distribute data from a file to multiple pipelines for different processes: pipe "(end ?) < inputfile!f:fanout!process1 ? f:! process2 ? f: ! process3 " ¤ (end ?) assigns ? as the pipeline end character. ¤ < inputfile Read file content into pipeline ¤ f:fanout defines a label f for the FANOUT stage. The FANOUT stage dispatches all records through all connected output streams connected with f: label. ¤ process1 could be a serie of stages to manipulate data and take different actions ¤ ? marks the end of the first pipeline. ¤ f: references the label f on the FANOUT stage in the first pipeline and defines the secondary output stream for the FANOUT stage. The records from the secondary output stream of the FANOUT stage in the first pipeline flow to the following stage process2. ¤ process2 could be a serie of stages to manipulate data and take different actions ¤ ? marks the end of the second pipeline. ¤ f: references the label f on the FANOUT stage in the first pipeline and defines the tertiary output stream for the FANOUT stage. The records from the tertiary output stream of the FANOUT stage in the first pipeline flow to the following stage process3. ¤ process3 could be a serie of stages to manipulate data and take different actions Figure 1 shows the flow of the records: *---------* *---------* *---------* | < |---->| |------------------->| process1| |inputfile| | f:fanout|-----+ | | | | | |--+ | *---------* +---------+ +---------+ | | | | *---------* | +------------->| process2| | | | | *---------* | | *---------* *---------------->| process3| | | *---------*

Stage: GATE


Syntax

 
 >>---- GATE ----.------------.-------------><
                 '-- STRICT --'
 
 

Purpose

 
 Use the GATE stage command to end portions of a pipeline.  GATE copies records
 from its secondary input stream and higher-numbered input streams to the
 corresponding output streams until it determines that a record has arrived on
 its primary input stream.  GATE then ends, which causes all of its input and
 output streams to be severed.  The severing of these streams may cause other
 stages to end, depending on the configuration of the pipeline.
 
 GATE can operate in two different modes, depending on whether the operand
 STRICT is specified.  When STRICT is specified, whenever GATE receives a
 record on any input stream other than its primary input stream, it does not
 read that record until after it has first checked to be sure that no record
 has arrived on its primary input stream.  Thus, when a record arrives on its
 primary input stream, it will read no more input records from any input
 stream.
 
 When STRICT is not specified, GATE may read some number of records from a
 higher-numbered stream before noticing that it has received a record on its
 primary stream.  In this mode, GATE may continue reading from a given stream
 until that stream has no more records.  Only then does it check to see whether
 the primary input stream has a record.
 

Operands

 
 
 STRICT
     specifies that GATE is to check for a record on its primary input stream
     before reading any record that arrives on any other input stream.

Streams

 
 PRIMARY INPUT STREAM:  GATE does not read records from its primary input
 stream.  It ends when a record arrives on its primary input stream.
 
 SECONDARY AND HIGHER-NUMBERED INPUT STREAMS:  GATE reads records from its
 secondary and higher-numbered input streams.  If all of its secondary and
 higher-numbered input streams reach end of file without a record arriving on
 its primary input stream, GATE ends.
 
 SECONDARY AND HIGHER-NUMBERED OUTPUT STREAMS:  If the secondary or
 higher-numbered output streams are connected, GATE copies records from its
 secondary or higher-numbered input streams to its corresponding output
 streams.
 

Examples

 

Example 1

Given the input file shown in Figure 1, use the following command to display all records in a file before the word 'cooldown'. The pipe cmd reads records from the file WORKOUT.FILE until it locates the word cooldown. When cooldown is located, the records stop flowing through the pipeline. pipe "(end ?) < WORKOUT.FILE ! l:locate /cooldown/ ! g:gate ? l: ! g: ! console" ¤ (end ?) assigns ? as the pipeline end character. ¤ < WORKOUT.FILE reads file WORKOUT.FILE into the pipeline. ¤ l:locate /cooldown/ defines a label l for the LOCATE stage. LOCATE writes all records containing cooldown to its primary output stream. LOCATE writes all records that do not contain cooldown to its secondary output stream. ¤ g:gate defines a label g for the GATE stage. GATE reads the records it receives on its secondary input stream (which is connected to the secondary output stream of the LOCATE stage) and copies them to its secondary output stream. When it receives a record on its primary input stream (which is connected to the primary output stream of the LOCATE stage), it ends immediately without consuming that record. Thus, it ends as soon as LOCATE selects the first record containing the string cooldown. When GATE ends, its output stream and both of its input streams are severed. The CONSOLE stage then receives end of file on its input stream and ends. When the LOCATE stage discovers that neither of its output streams is connected, it too ends, thus severing its primary input stream, which then causes the < stage also to end. ¤ ? marks the end of the first pipeline and the beginning of the second pipeline. ¤ l: references the label on the LOCATE stage in the first pipeline and defines the secondary output stream for the LOCATE stage. LOCATE writes all records not containing cooldown to its secondary output stream. ¤ g: references the label on the GATE stage of the first pipeline and defines the secondary input stream and secondary output stream for the GATE stage. GATE passes records from its secondary input stream to its secondary output stream. In this example, all records that do not contain cooldown and arrive before the first occurrence of cooldown are written to the secondary output stream of GATE and then passed to the CONSOLE stage that follows. ¤ console writes the records to the terminal. WORKOUT.FILE ===== * * * Top of File * * * ===== warm-up ===== touch-toes ===== flexibility ===== strength ===== bench-press ===== cooldown ===== breathe ===== relax ===== * * * End of File * * * Figure 1. GATE Stage Command Example: Input File Contents Figure 2 shows the resulting console output after the pipeline command is executed. warm-up touch-toes flexibility strength bench-press Figure 2. GATE Stage Command Example: Command and Terminal Output

Example 2

The following shell issues a 'w' command every 5 seconds, and displays the results at the terminal. While this shell is executing, it passes to Linux any console commands until a stop command is entered. When stop is entered, a record is passed to GATE's primary input stream which causes GATE to end. When GATE ends, its input and output streams are severed creating a cascading effect and eventually causing all stages in this pipeline to end. +----------------------------------------------------------------------------+ | | | # | | # wout.sh | | # | | pipe "(end ? comments # ) | | cons eof /stop/ # Get command from user until stop | | ! s:locate /stop/ # If it get stop pass to GATE | | ! g:gate strict # End when stop is received | | # and this will cause the ending | | # of the other stages as well | | ? | | ! literal +00:00:05 # Set up 5-second delay | | ! duplicate * # Make infinite copies of record | | ! delay # Pass a record every 5 seconds | | ! g: # GATE will end | | ! specs /w/ 1 # Change record to 'w' command | | ! command # Issue the 'w' command | | ! console # Display the results | | ? | | s: # All commands without stop | | ! g: # GATE will end | | ! command # Linux will execute commands | | ! console" # Display result at terminal | +----------------------------------------------------------------------------+ Note: You can write pipeline command in a very readible style with comments under Linux (Aix) by respecting following: ¤ first line of command must begin with ' pipe " ' without closing " ¤ on each line, you can write a stage with comments ¤ in case of comments, you have to specify the comments character in pipe options (see example) ¤ in your command, you must not put any pipeline sep/end characters (!?) ¤ on the line of endcharacter (?)=, you van not put comments, else treated as stage!! ¤ the last line of stages must ends with "

Stage: GATHER


Syntax

 
               .-- STOP --- ALLEOF --------------------------------.
 >>-- GATHER --+---------------------------------------------------+-----><
               |-- STOP--.-- ALLEOF --.----------------------------|
               |         |-- ANYEOF --|                            |
               |         '-- n -------'                            |
               |                                                   |
               '-- STREAMid ----.-------------------------------.--'
                                '-| Separator |--| Inputrange |-'
 
 Separator:
 |--.-------------------------------------------.-----------------------|
    '--.-- WORDSEParator ---.--.-- char -----.--'
       |-- WS --------------|  |-- hexchar --|
       |-- FIELDSEparator --|  |-- BLANK ----|
       '-- FS --------------'  '-- SPACE ----'
 
 Inputrange:
            (1)
 |--.-- Words ------- wnumberrange ----.---|
    |        (1)                       |
    |-- Fields ------- fnumberrange ---|
    '-- cnumberrange ------------------'
 
 Notes:
 (1)  Blanks are optional in this position.
 

Purpose

 
 Use the GATHER stage command to read records from its connected input streams
 in either sequential or some other specified order, and write records to its
 connected primary output stream.
 
 GATHER, without operands, writes the first record from its primary input
 stream to its connected primary output stream, the first record from its
 secondary input stream to its primary output stream, and so on, until one
 record has been written from each connected input stream.  GATHER repeats this
 processing cycle in sequential order until all records from all connected
 input streams are processed or end of file is reached.  GATHER without
 operands, or with the STOP operand, bypasses unconnected input streams.
 
 Specify the STOP operand to tell GATHER when to stop processing.  The STREAMID
 operand indicates which input streams GATHER should read and in what order.
 When the STREAMID operand is specified, the GATHER stage command inspects the
 first primary input stream record and searches for the stream identifier
 according to the specified input range.  GATHER then reads the identified
 input stream and writes it to its primary output stream.  If the stream
 identifier directs GATHER to read from a non-primary input stream, it writes
 that record first and then consumes the primary input stream record.
 
 

Operands

 
 STOP
     specifies how many input streams must be at end of file for GATHER to stop
     processing input records.  STOP ALLEOF is the default.
 
 ALLEOF
     specifies that input records will stop being processed when GATHER
     determines that all its input streams are no longer connected.  Input
     records continue to be written as long as at least one input stream is
     connected.  STOP ALLEOF is the default.
 
 ANYEOF
     specifies that input records will stop being written as soon as GATHER
     determines that any one of its input streams is no longer connected.
 
 n
     is the number of streams required to become unconnected and reach end of
     file before GATHER stops writing records.  Specify a decimal number of 1
     or greater.  Specifying 1 is the same as specifying ANYEOF.
 
 STREAMid
     identifies the location in the primary input record that contains the
     stream identifier identifying a particular input stream that GATHER will
     read.  The stream identifier can be a decimal number, where 0 is the
     primary input stream, 1 is the secondary input stream, and so on.
 
 WORDSEParator
 WS
     specifies the character that is used to separate words in the input
     records.  For example, use WORDSEP to specify that the dash separates each
     word:
 
       pipe "literal 000-in-rec ! gather streamid wordsep - w1 ! console" 
       000-in-rec
 
     The primary input stream is indicated by the first word, 000, so GATHER
     writes the primary input stream record to its primary output stream.
 
     A blank is used as the default for WORDSEPARATOR (or WS).
 
 FIELDSEparator
 FS
     specifies the character that is used to separate fields in the input
     records.  For example, use FIELDSEP to specify that the plus sign
     separates each field:
 
       pipe "literal 000+in-rec ! gather streamid fieldsep + f1 ! console" 
       000+in-rec
 
     The primary input stream is indicated by the first field, 000, so GATHER
     writes the primary input stream record to its primary output stream.
 
     X'05' is the default field separator character.
 
 char
 hexchar
     is the single character, char, or the 2-character hexadecimal
     representation of a character, hexchar.  Do not enclose the hexadecimal
     representation in quotation marks.
 
     Use char or hexchar with:
 
       o WORDSEPARATOR (or WS) to specify the word separator character.
 
       o FIELDSEPARATOR (or FS) to specify the field separator character.
 
 BLANK
 SPACE
     specifies that a blank is used as the:
 
       o Word separator character when specified with the WORDSEPARATOR (or WS)
         operand.
 
       o Field separator character when specified with the FIELDSEPARATOR (or
         FS) operand.
 
 Words
     specifies, in terms of delimited character strings (words), the input data
     that the GATHER stage command will use as a stream identifier.  The
     WORDSEPARATOR (or WS) operand defines the character that delimits words.
     For example, the input stream in the following pipeline consists of one
     record with three words separated by the default word separator (blank):
 
       pipe "literal in rec 0 ! gather streamid w3 ! console" 
       in rec 0
 
     The primary input stream is indicated by the third word, 0, so GATHER
     writes the primary input stream record to its primary output stream.
 
 
 Fields
     specifies, in terms of delimited fields, the input data that the GATHER
     stage command will use as a stream identifier.  The FIELDSEPARATOR (or FS)
     operand defines the character that delimits fields.
 
 
 wnumberrange
 fnumberrange
 cnumberrange
     defines a specified location of the input data as a range of word numbers,
     field numbers, or column numbers which GATHER uses to determine the stream
     identifier of the input stream it is to read from.  The location is
     relative to the beginning or the end of the record.  A negative number in
     the range indicates that the range is relative to the end of the record;
     otherwise, the range is relative to the beginning of the record.  If you
     do not specify a location, GATHER uses the entire input record as the
     stream identifier, so your record must contain up to 4 alphabetic
     characters or a combination of alphabetic characters and digits that
     includes at least one alphabetic character.  You can specify a location as
     follows:
 
     location
     -location
         is a single column number, word number, or field number.  -location is
         relative to the end of the record.  The last location in the record is
         -1.
 
     location1-location2
     location1;location2
     -location1;location2
     location1;-location2
     -location1;-location2
         is a range of columns, words, or fields beginning with location1 and
         ending with location2, inclusive.  If you specify both locations
         relative to the beginning of the input record, (that is, you use
         location1 and location2), location2 must be numerically equal to or
         greater than location1.  If you specify both locations relative to the
         end of the input record, (that is, you use -location1 and -location2),
         location2 must be numerically less than or equal to location1.
 
         If you specified WORDS or FIELDS, -2;-1 specifies that the
         second-from-last word or field and the last word or field is the input
         location.
 
         If you specify location1;-location2 or if you specify
         -location1;location2, the position in the record defined by location1
         must occur before the position in the record defined by location2.
         For example, no positions in the input record to GATHER are searched
         if you specify -8;6 for an input record that contains 15 columns since
         location1 is positioned after location2 in the record.
 
     location1-*
     location1;*
     -location1;*
         is a range of columns, words, or fields beginning with location1 and
         ending with the last column, word, or field of the record, inclusive.
 
     *-location2
     *;location2
     *;-location2
         is a range of columns, words, or fields beginning with the first
         column, word, or field of the record and ending with location2,
         inclusive.
 
     *-*
     *;*
         is a range of columns, words, or fields beginning with the first
         column, word, or field of the record and ending with the last column,
         word, or field of the record, inclusive.
 
     location1.n
         is a range of n columns, words, or fields beginning with location1.
         You can specify any number from 1 to 2(31) -1 for n.

Streams

 
 INPUT STREAMS:  GATHER reads one record from each connected stream in
 sequential order, starting with the primary input stream unless otherwise
 specified.  GATHER, without the STREAMID operand, bypasses records on streams
 that are not connected and have reached end of file.  If STREAMID is
 specified, and a non-primary input stream is identified on the primary input
 stream record that GATHER has inspected, GATHER reads the non-primary input
 record first, and then consumes the primary input stream record.
 
 PRIMARY OUTPUT STREAM:  GATHER writes its input records to its primary output
 stream in the same order it reads the input records.
 

Examples

 

Example 1

This example combines three input streams into one output stream with the GATHER stage command. gather1.pipe
#
#  gather1.pipe
#
(endchar ?)
  < ORDNUM                                  # read order number file
! G:gather                                  # read input streams 0,1,2
! specs 1-15 1 /FOR CUSTOMER/ nextword      # arrange input data
        read 1-22 30 write
        read 1-16 1 /IS/ nextword 17-24 nextword
        write / / 1
! console                              # write records to output file
  ?                                    # start of second pipeline
  < CUST                               # read customer file
! G:                                   # define GATHER's secondary input
  ?                                    # start of third  pipeline
  < ACCOUNT                            # read account file
! G:                                   # define GATHER's tertiary input
¤ (endchar ?) assigns ? as the pipeline end character. ¤ < ORDNUM reads the file ORDNUM into the pipeline. This flows as input into the GATHER stage command. ¤ gather reads one record from each of its connected input streams in sequential order, starting with the primary input stream. It reads the first record from ORDNUM, the first record from the CUST on its secondary input stream, and the first record from the ACCOUNT on its tertiary input stream. GATHER repeats this cycle three times until all records are consumed and written to the console on its primary output stream. ¤ specs arranges the contents of the input records and adds words for a meaningful accounting report. ¤ 1-15 1 /FOR CUSTOMER/ nextword writes the data from columns 1 through 15 to the output record beginning in column 1. The character string FOR CUSTOMER is written as the next word in the output record, starting in column 17 and following the order number and a blank. ¤ read releases the current input record (primary stream) and reads the next record, which is the secondary input stream record. ¤ 1-22 30 reads the contents of the secondary input stream record in columns 1 through 22 and writes the data to the output record beginning in column 30. ¤ write writes the record written so far to the primary output stream. ¤ read releases the current input record (secondary stream) and reads the next record, which is the tertiary input stream record. ¤ 1-16 1 /IS/ nextword 17-24 nextword reads the contents of the tertiary input stream record in columns 1 through 16 and writes the data to the output record beginning in column 1. A blank is added in the next available column and SPECS writes the character string IS in the output record. Then SPECS reads the contents of the tertiary input stream record from columns 17 through 24, and writes a blank and the data in the output record. ¤ write writes the record written so far to the primary output stream. ¤ / / 1 writes a blank in the output record beginning in column 1. This leaves a blank line between each account written. ¤ console writes the records to the console. This is the last stage of the first pipeline. ¤ ? marks the end of the first pipeline. ¤ < CUST reads the file CUST into the pipeline. ¤ g: references the label g on the GATHER stage of the first pipeline and defines the secondary input stream for the GATHER stage. The record from the previous < stage command flows to the GATHER stage as its secondary input stream. ¤ ? marks the end of the second pipeline. ¤ < ACCOUNT reads the file ACCOUNT into the pipeline. ¤ g: references the label g on the GATHER stage of the first pipeline and defines the tertiary input stream for the GATHER stage. The record from the previous > stage command flows to the GATHER stage as its tertiary input stream. ORDNUM
                                               
ORDER # 123456                                               
ORDER # 788994                                               
ORDER # 123330                                               
CUST
                                               
AMERICAN FIELDSERVERS                                               
TAHITIAN FLYCATCHERS                                               
NIMBA NETS                                               
ACCOUNT
                                               
ACCOUNT BALANCE $0.00                                               
ACCOUNT BALANCE $1000.00                                               
ACCOUNT BALANCE $-20.00                                               
Results
                                               
pipe "runfile gather1.pipe"                                               
ORDER # 123456  FOR CUSTOMER AMERICAN FIELDSERVERS                                               
ACCOUNT BALANCE  IS $0.00                                               

ORDER # 788994  FOR CUSTOMER FAHITIAN FLYCATCHERS                                               
ACCOUNT BALANCE  IS $1000.00                                               

ORDER # 123330  FOR CUSTOMER NIMBA NETS                                               
ACCOUNT BALANCE  IS $-20.00                                               

Example 2

In this example, GATHER has three input streams connected, but writes out only the tertiary input stream record as directed by the stream identifier in the primary input stream record selected by the LOCATE stage. gather2.pipe
                                               
#                                               
#  gather2.pipe                                               
#                                               
(endchar ?)                                               
  < INPUT                            # read the input file                                               
! locate /0002/                      # find records containing 0002                                               
! g:gather streamid wordsep - w2     # identify stream to read from                                               
! console                            # display records to terminal                                               
  ?                                  # start of second pipeline                                               
  literal SECONDARY INPUT STREAM 01  # provide secondary input rec                                               
! g:                                 # define GATHER's secondary input                                               
  ?                                  # start of third pipeline                                               
  literal TERTIARY INPUT STREAM 02   # provide tertiary input rec                                               
! g:                                 # define GATHER's tertiary input                                               
¤ (endchar ?) assigns ? as the pipeline end character. ¤ < INPUT reads the file INPUT FILE into the pipeline. ¤ locate /0002/ searches each input file record for the string 0002. LOCATE writes the record it finds that matches the search criteria to its primary output stream. This flows as input into the GATHER stage command. ¤ g: gather streamid wordsep - w2 assigns a label g for the GATHER stage. GATHER is able to read from any of its multiple input streams and write to its primary output stream. The STREAMID operand directs GATHER to inspect its primary input stream record for the second word that contains a stream identifier. The words in the primary input stream record are separated by a -. GATHER finds the tertiary input stream identified, and reads a record from that connected input stream. ¤ console writes the tertiary record to the terminal. This is the last stage of the first pipeline. ¤ ? marks the end of the first pipeline. ¤ literal SECONDARY INPUT STREAM 01 writes words comprising a record into the pipeline on GATHER's secondary input stream. ¤ g: references the label g on the GATHER stage of the first pipeline and defines the secondary input stream for the GATHER stage. The record from the previous LITERAL stage command flows to the GATHER stage as its secondary input stream. ¤ ? marks the end of the second pipeline. ¤ literal TERTIARY INPUT STREAM 02 writes words comprising a record into the pipeline on GATHER's tertiary input stream. ¤ g: references the label g on the GATHER stage of the first pipeline and defines the tertiary input stream for the GATHER stage. The record from the previous LITERAL stage command flows to the GATHER stage as its tertiary input stream. INPUT
                                               
Primary Input Stream Record-0001-Stream Identifier                                               
Primary Input Stream Record-0002-Stream Identifier                                               
Primary Input Stream Record-0003-Stream Identifier                                               
Results
                                               
pipe "runfile gather2.pipe"                                               
TERTIARY INPUT STREAM 02                                               

Stage: JUXTAPOSE


Syntax

 
 
 >>-- JUXTAPOSE ---------------------------------------------------------------><
 
 
 

Purpose

 
 Use the JUXTAPOSE stage command to prefix one or more records in its secondary
 input stream with a record from its primary input stream.  JUXTAPOSE reads
 records from its primary and secondary input streams as they become available.
 Each record from the primary input stream is stored in a one-record buffer,
 replacing the previous contents of the buffer.  The record which was
 previously in the buffer is then discarded.  When a record is read from the
 secondary input stream, it is prefixed with the record currently in the buffer
 and the combined record is written to the primary output stream.  If a record
 is available on the secondary input stream before a record is available on the
 primary input stream, the secondary input stream record is not prefixed.
 

Operands

(operands not available)

Streams

 
 
 SECONDARY INPUT STREAM:  JUXTAPOSE reads records from its secondary input
 stream as they become available and prefixes the records with the record
 currently in the buffer.
 
 PRIMARY OUTPUT STREAM:  JUXTAPOSE writes the combined records to its primary
 output stream.

Examples

Example 1

The following pipeline command file, USERDIR.PIPE, reads the file USER.DIRECT and prefixes each MDISK statement with the corresponding user ID. (USER.DIRECT is an abstract of the VM CP Directory) USERDIR.PIPE
(endchar ? )
  < USER.DIRECT      # Read the CP directory
! l: nfind MDISK     # Get records that don't start with MDISK
! find USER          # Get records that begin with USER
! specs w2 1.8       # Pull user ID from record
! j: juxtapose       # Preface MDISK with user ID
! console            # Display output to console
  ?                  # Start of second pipeline
  l:                 # Define secondary output for nfind
! j:                 # Define secondary input for juxtapose
¤ (endchar ?) assigns ? as the pipeline end character. ¤ < USER.DIRECT reads the input file USER.DIRECT. ¤ l: nfind MDISK defines a label l for the NFIND stage. NFIND searches the file USER.DIRECT for all records that begin with MDISK. All records that begin with MDISK are written to the secondary output stream, and all records that do not begin with MDISK are written to the primary output stream. ¤ find USER searches the records from the primary output stream of the NFIND stage (all records that do not begin with MDISK) for the statements that begin with USER. ¤ specs w2 1.8 Keep userid and put it at column 1 on 8 columns. ¤ j: juxtapose defines a label j for the JUXTAPOSE stage. JUXTAPOSE reads its primary input stream which contains the user ID from the statements in the input file. JUXTAPOSE then reads the MDISK statements from its secondary input stream and prefixes the corresponding user ID to each MDISK statement before the combined record is written to the primary output stream. ¤ console writes the records to the terminal. It is the last stage in the first pipeline. ¤ ? marks the end of the first pipeline and the beginning of the second pipeline. ¤ l: references the label on the NFIND stage in the first pipeline and defines the secondary output stream for the NFIND stage. ¤ j references the label on the JUXTAPOSE stage in the first pipeline and defines the secondary input stream for the JUXTAPOSE stage. USER.DIRECT
USER JOHN XXXXXXX 06M 16M G 64
MACHINE XA
IPL CMS PARM AUTOCR
LINK MAINT 0090 0090 RR
LINK MAINT 019E 019E RR
MDISK 0197 3380 1459 15 CMS786 MR
MDISK 0196 3380 337 10 CMS78A MR
MDISK 0194 3380 80 6 CMS982 MR
MDISK 0191 3390 2028 17 USE71D MR
MDISK 0195 3390 1493 5 USE796 MR
USER WILL XXXXXXX 06M 16M G 64
MACHINE XA
IPL CMS PARM AUTOCR
LINK MAINT 0090 0090 RR
LINK MAINT 019E 019E RR
IPL CMS PARM AUTOCR
MDISK 0191 3390 1028 10 USE71X MR
MDISK 0195 3390 0493 3 USE794 MR
Running this exec displays the following output: Results
                                               
pipe "runfile USERDIR.PIPE" 
JOHN    MDISK 0197 3380 1459 15 CMS786 MR
JOHN    MDISK 0196 3380 337 10 CMS78A MR
JOHN    MDISK 0194 3380 80 6 CMS982 MR
JOHN    MDISK 0191 3390 2028 17 USE71D MR
JOHN    MDISK 0195 3390 1493 5 USE796 MR
WILL    MDISK 0191 3390 1028 10 USE71X MR
WILL    MDISK 0195 3390 0493 3 USE794 MR

Stage: COMMAND


Syntax

 
 >>-- COMMAND --.------------.--------------------------------><
                '-- string --'
 
 

Purpose

 Use the COMMAND stage command to issue OS commands from a pipeline and to
 write the responses from the commands to the pipeline rather than the
 terminal.  If an operand is specified, it is passed as a command to OS (Aix, Linux, ...) for
 execution. No Operating System piped command is allowed (ex: ls -al | cut -f1 ...| ..).
 Then, any primary input stream records are read and passed as commands.
 Each line of output is written as a separate record.
 
 If its secondary output stream is connected, the COMMAND stage command writes
 all line mode output from a command to its primary output stream and then
 writes the return code from that command to its secondary output stream.  This
 is repeated for each command issued by the COMMAND stage command.
 
 Operating Systems considerations:
 
 Aix, Linux:
	On these systems, any command is correctly executed, but you can't pass 
	a piped command, only single commands are allowed (java Process class functionning..).
   ex:  pipe "command ls -al | cut -f1 ! console"   => Exception in process class
  
      to 'simulate' the OS piped command process as:
        pipe "command ls -al ! command cut -f1 ! console" 
 
 Windows:
	Unfortunately, the Java Win32 portable runtime doesn't react as under Aix,Linux
	due to the command.com program structure...
   So, unable to pass run command stage under windows... maybe in the future.
  
   You can write your own windows stage by:
      1. Reading command to run
      2. Write down command string into a temporary file (.bat) with redirecting output to a temp file
      3. Run the .bat file just created in 2.
      4. Reading output in the temp file
 

Operands

 string
     is a command to pass to Operating System for execution.

Streams

 PRIMARY INPUT STREAM:  The COMMAND stage command reads records from its
 primary input stream.  Input records act as:
 
     commands to be exectued if COMMAND stage has no parameter
  or line of data to be processed by the command passed in COMMAND stage
 
 
 PRIMARY OUTPUT STREAM:  The COMMAND stage command causes any line mode output
 from the commands to be written to its primary output stream.  Each line of
 output is written as a separate record.
 
 SECONDARY OUTPUT STREAM:  If its secondary output stream is connected, the
 COMMAND stage command writes the return code from each command to its
 secondary output stream after any line mode output from that command has been
 written to its primary output stream.
 
 TERTIARY OUTPUT STREAM:  If its tertiary output stream is connected, the
 COMMAND stage command writes all the error messages issued by the command.

Examples

 
Only Aix/Linux examples will be given due to the 'non functionning' under windows...(see purpose)
 
Example 1 
  
    To list all the files in current directory, reaarange records and display result:
   
    [linux]$ pipe "command ls -al ! specs word -1 1 w5 20.10 right ! cons" 
    208
    .                        1024
    ..                       1024
    pipe                       95
    pipe.html               56442
    pipeline.jar           138142
    tmp                        22
    w3                      10803
 
    To suppress header line (208 in result above), append 'drop 1' stage before specs stage.
 
Example 2 
  
   To run multi lines of commands, 
 
     [linux]$ pipe "literal ls -al!literal w!literal hostname!command!cons" 
     laurent
      12:47pm  up 2 days, 21:45,  1 user,  load average: 0.00, 0.00, 0.00
     USER     TTY      FROM              LOGIN@   IDLE   JCPU   PCPU  WHAT
     lolo     pts/0    lparis.sma.ibm.c Fri 1pm  3.00s  2.76s  0.02s  /bin/sh ./pipe
     total 209
     drwxr-xr-x   2 lolo     root         1024 May 11 18:24 .
     drwx------   9 lolo     root         1024 May  9 15:18 ..
     -rwx------   1 lolo     root           95 May  9 15:34 pipe
     -rw-r--r--   1 lolo     root        56442 May 11 18:21 pipe.html
     -rw-r--r--   1 lolo     root       138663 May 12 12:46 pipeline.jar
     -rw-r--r--   1 lolo     root           22 May 11 18:24 tmp
     -rw-r--r--   1 lolo     root        10803 May 11 14:11 w3
 
Example 3
     To retrieve return code and/or error messages, issue your pipeline as:
  
     pipe "(end ?) c:command mycommand ! cons ? c: ! specs /Rc=/ 1 1-* n ! cons ? c:!specs /Err:/ 1 1-* n !cons " 
          -------------.--------------   --.-   -------------.-----------------   -.----------------------------
                       |                   |                 |                     |
                       |                   |                 |                     |
                       |                   |                 |                     +--> thrird pipeline containing Errors  
                       |                   |                 +------------------------> second pipeline containg return code
                       |                   +------------------------------------------> first pipeline containing command results 
                       +--------------------------------------------------------------> issue the command (using the connector 'c:' )    
 
 
Example 4
      To use pipeline stages in conjunction with native commands, write your pipeline command as:
  
      [linux]$ pipe "command ls -al ! specs w-1 1!command grep pipe ! cons" 
      pipe
      pipe.html
      pipeline.jar 
  
 

Stage: DAEMON


Syntax

 
 >>-- DAEMON ---.------------.--------------------------------><
                '-- string --'
 
 

Purpose

 Use the DAEMON stage to launch commands/processes from a pipeline.
 If an operand is specified, it is passed as a command to the operating system for
 execution.
 The DAEMON stage will write nothing into its primary output stream as it launches
 the command (or process) without waiting for its completion.

Operands

 string
     is a command to pass to Operating System for execution.

Streams

 PRIMARY INPUT STREAM:  The DAEMON stage command reads records from its
 primary input stream.  Input records act as:
 
     commands to be exectued if DAEMON stage has no parameter
  or line of data to be processed by the command passed in DAEMON stage
 
 

Examples

 
Example 1 
  
    To launch the windows calculator (calc.exe) :
   
    C:\> pipe "literal calc.exe!daemon" 
 
Example 2 
  
   To launch two processes (p1, p2) at specified time:
 
     [linux]$ pipe "(end ?) literal 12:30 p1!deal!specs w2 1!daemon ? literal 15 p2!deal!specs w2 1!daemon" 
  
         ¤ (end ?)                    character to separate pipelines
           ------------ first pipeline --------------------------------------
         ¤ literal 12:30 p1           put the string '12:30 p1' into pipeline
         ¤ delay                      wake me up at 12:30:00
         ¤ specs w2 1                 put the second word into output (p1)
         ¤ daemon                     launch the p1 process
           ------------ second pipeline --------------------------------------
         ¤ literal 15 p2              put the string '12:30 p1' into pipeline
         ¤ delay                      wake me up at 15:00:00
         ¤ specs w2 1                 put the second word into output (p2)
         ¤ daemon                     launch the p2 process

Stage: APL


Syntax

 >>--APL--| expression |-----------------------------------------------------><
 
 where expression is a valid APL statement, if expression doesn't exist
 then APL stage takes apl statement from its primary input stream.
 
 

Purpose

 Use the APL stage command to run specific APL statement according
 to the APL language.
 For more detail about APL syntax and operators,
    type:   apl )help ! console 
 
 )help    is the online help keyword in the APL sub environment

Operands

 
 expression
     any valid APL statement.
 

Streams

 PRIMARY INPUT STREAM:  APL reads records from its primary input stream if connected
 
 PRIMARY OUTPUT STREAM:  APL copies result of APL statement to its primary output stream.
 

Examples

Example 1

To display general help of APL subEnvironment apl )help !cons

Example 2

To get prim numbers less than 100, pass following command: Results
pipe " apl (2=+/0=A°.|A)/A<-{iota}100 ! specs /First prim numbers are:/ 1 1-* nw !cons "
First prim numbers are:  2  3  5  7  11  13  17  19  23  29  31  37  41  43  47  53  59  61  67  71  73  79  83  89  97 
    
 

Example 3

To make the sum of list notes in student DB students.db
Student      Maths    Phys    Nature    Psy 
-------      -----    ----    ------    ----
0001            12      15         8       9
0002             7       6         3       6
0003            18      12        15      13
Results
pipe "< students.db ! drop 2 ! specs ,(+/A):{rho}A<-, 1 w2-* nw! apl ! console"
 11 
 5.5 
 14.5 	
    



Stage: NOTES


Syntax

 
 
 >>- NOTES ---| sep1 |---| Server |---| Database |---| Object |---| Request |------------>
 
 
 
 sep1:
 |--.----------------------------.-----------------------|
    '--- SEParator --- sepobj ---'
 
 Server:
 |--.--------------------------.-----------------------|
    '--- SERVER --- srvname ---'
 
 
 Database:
 |--.--------------------------------.-----------------------|
    '--.-- Database --.--- dbname ---'
       '----- DB -----'
 
 
 Object: (to specify with GET or SET request)
 |--.----------------------------.-------.------------------------------.----|
    '--- SEParator --- sepatt ---'       |--- ACL -------- aclentry ----|
                                         |--- AGENT ------ agentname ---|
                                         '--- DOCUMENT --- uniqueid ----'
 
 
 Request:
 |--.----------------------------------.----------|
    |--- LIST ------ notesobject ------|
    |                                  |
    |             <------ , -----<     |
    |--- GET ------- objproperty ------|
    |                                  |
    |             <------ , -----<     |
    '--- SET ------- objproperty ------'
 
 
 

Purpose

(purpose not available)

Operands

 
 SEParator
     This option allows you specify a separator for object properties, or object property attributes.
 
 sepobj 
     car to separate values of properties retrieved for an object.
     default is ,
 
 SERVER
     This option allows you specify the server hosting the Database.
     If not specified, DB is local.
 
 srvname 
     name of the server where the database is hosted. 
 
 DATABASE
 DB
     Option to specify the Databse you want to access.
 
 dbname
     name of the database. You have to indicate the full path, else the 
     answer will be DB not found (in secondary output stream).
 
 sepatt 
     car to separate values of all the attributes for a specific property.
     By instance, to separate roles when you request roles list of an aclentry.
     default is ;
 
 ACL
     Option to GET or SET ACL properties for the selected Database.
 
 aclentry
     name of the entry in ACL for which you want to get/set properties.
 
 AGENT
     Option to GET or SET Agent properties for the selected Database.
 
 agentname
     name of the agent for which you want to get/set properties.
 
 
 LIST
     Option to List properties of a specific database object, such as:
     ACL, AGENTS 
 
 
 GET
     Option to GET properties of a specific Db object (aclEntry, Agent, Document,...)
 
 SET
     Option to SET properties of a specific Db object (aclEntry, Agent, Document,...)
     values to be set are taken from primary input stream.
 
 notesobject
      Values are:
          ACL                to get a complete report about the DB ACL.
          AGENTS             to get a complete report about the DB AGENTS
 
 
 objproperty
      Properties for the database object. Values are depending on the type of
      object you selected and are:
    
      for AclEntry, values are:
 
          ISCANCREATEDOCUMENTS
          ISCANDELETEDOCUMENTS
          ISCANCREATEPERSONALAGENT
          ISCANCREATEPERSONALFOLDER
          ISPUBLICREADER
          ISPUBLICWRITER
          LEVEL
          ROLES
 
      for Agent, values are:
 
          COMMENT
          COMMENTOWNER
          NAME
          ISENABLED
          ISPUBLIC
          OWNER
          QUERY
          SERVERNAME
 
 

Streams

(streams not available)

Examples

(examples not available)

Stage: ABBREV


Syntax

 
  >>---- ABBREV ----.---------------------------------------------------.---><
                    '--- word ---.----------------------------------.---'     
                                 '--- number ---.---------------.---'         
                                                '--- ANYcase ---'             
 

Purpose

 Use the ABBREV stage command to select records that contain an abbreviation 
 of a specified word in the first positions.
 Records that don't match abbreviation are copied to secondary output stream if connected
 else they are discarded.

Operands

 word
 		specify the characters to compare against the beginning of input records.
 		If you don't specify word, ABBREV selects empty records and those beginning with a blank.

 number
		Indicate the minimum count of characters to take for abbreviation.
		Default is the length of the word (different from CMS Pipeline which is 0)

 ANYcase
		To make comparison case insensitive.
 

Streams

 PRIMARY INPUT STREAM:  	ABBREV reads records from its primary input stream.

 PRIMARY OUTPUT STREAM:	ABBREV copies its primary input stream records to its
                       	primary output stream if they match abbreviation.

 SECONDARY OUTPUT STREAM:	ABBREV copies its primary input stream records to its
                         	secondary output stream if they DO NOT match abbreviation.

Examples

Example 1

To select records for sub-code 'string' with three characters minimum: Results
pipe "literal st str string !split ! abbrev string 3 !cons" 
str
string

Stage: ALL


Syntax

 >>--ALL--| expression |-----------------------------------------------------><
 
 expression:
 
    <----- ! ---------< (2)
    <----- | ---------< (1)
 |----| stringdef |-----------------------------------------------------------|
 
 stringdef:
    <------------------------ & ------------------< (1)
 |----.-----.--.---------- /string/ ----------.-----------------------------------------|
      '- ^ -'  |--------- Xhexstring ---------|
               |--------- Hhexstring ---------|
               |--------- Bbinstring ---------|
               |--------| expression |--------|
               '-- ( ---| expression |--- ) --'
 
 Note:
 (1)  Blanks are optional between the logical operators and the strings.
 (2)  OR operator can be | or ! depending on the stage separator you are using...
 

Purpose

 Use the ALL stage command to select all records containing a specified string
 or strings determined by an expression.  The expression can be a character
 string, hexadecimal character string, binary string, or a combination of
 character strings, hexadecimal character strings, binary strings, and logical
 operators.  All records that contain the string or strings determined by the
 expression are written to the primary output stream in the order found in the
 input stream.
 
 If the secondary output stream is connected, ALL writes all the records that
 do not contain the string or strings determined by the expression to its
 secondary output stream.  If the secondary output stream is not connected, ALL
 discards these records.

Operands

 ^
     negates the selection criteria for the specified string or expression
     which immediately follows the ^ operand.
 
 /(diagonal)
     signifies any nonblank delimiting character that does not appear in
     string.
 
     You cannot use a B, b, X, x, H, h, % , (, or ) for a delimiting character.
 
 string
     specifies a string of characters to be located.
 
 Xhexstring
 Hhexstring
     specifies a string of hexadecimal characters, following the X or H, that
     defines the string of characters to be located.  The X or H can be
     specified in uppercase or lowercase.  You must not specify any spaces in
     the string.  There must be an even number of hexadecimal characters in the
     string.
 
 Bbinstring
     specifies a string of 0's and 1's, following the B, that defines the
     string of characters to be located.  The B can be specified in uppercase
     or lowercase.  You must not specify any spaces in the string.  The number
     of binary digits must be divisible by 8.	
 
 !
 |
    is the symbol for the OR operation.  You can also use the vertical bar (|)
    as the OR operator.  The records containing any of the strings separated
    by a ! or | are selected.
 
 &
     is the symbol for the AND operation.  Only the records containing all of
     the strings separated by an & are selected.

Streams

 PRIMARY INPUT STREAM:  ALL reads records from its primary input stream.
 
 PRIMARY OUTPUT STREAM:  ALL copies input records that contain the string or
 strings determined by the expression to its primary output stream.
 
 SECONDARY OUTPUT STREAM:  If the secondary output stream is connected, ALL
 copies to its secondary output stream all input records not copied to its
 primary output stream.

Examples

Example 1

To display all records from the file math.file that contains the string 123 or a vertical bar (|), X'7C' (ascii), enter the following Pipeline command: < math.file ! all /123/ | x7c ! console math.file
This is a sample file
containing operations with 123, 456 and + sign and also the | sign
In some circonstances, | can be replaced by !...
Op1:    123+Log(50)
Op2:    123+456 - 3x89
Op3:    456*5
Op4:    456+log(12)
Op5:    sin(x)+cos(x)
Results
pipe "< math.file ! all /123/ | x7c ! console"
containing operations with 123, 456 and + sign and also the | sign
In some circonstances, | can be replaced by !...
Op1:    123+Log(50)
Op2:    123+456 - 3x89

Example 2

To display all records from the file math.file that contains a plus sign (+) and 123, 456, or both, enter the following PIPE command: < math.file ! all (/123/ | /456/) & /+/ ! console math.file
This is a sample file
containing operations with 123, 456 and + sign and also the | sign
In some circonstances, | can be replaced by !...
Op1:    123+Log(50)
Op2:    123+456 - 3x89
Op3:    456*5
Op4:    456+log(12)
Op5:    sin(x)+cos(x)
Results
pipe "< math.file ! all (/123/ | /456/) & /+/ ! console"
containing operations with 123, 456 and + sign and also the | sign
Op1:    123+Log(50)
Op2:    123+456 - 3x89
Op4:    456+log(12)

Stage: FIND


Syntax

 
 
 >>--- FIND --.----------.---------------------------------><
              '-- text --'
 

Purpose

 Use the FIND stage command to select records that begin with a specified text.
 FIND reads records from its primary input stream and writes the records that
 begin with the specified text to its primary output stream, if it is
 connected.  If its secondary output stream is connected, FIND writes all other
 records to its secondary output stream.

Operands

 
 
 text
     is any text that you want to find, beginning in the first column of an
     input record.  Each character in text must exactly match the corresponding
     character in the input record.
 
     Uppercase and lowercase representations of the same alphabetic character
     do not match.  To be selected, an input record must be at least as long as
     text, including any trailing blanks specified in text.
 
     If you do not specify text, FIND copies all records in its primary input
     stream to its primary output stream.

Streams

 PRIMARY INPUT STREAM:  FIND reads records from its primary input stream.
 
 PRIMARY OUTPUT STREAM:  FIND copies each input record that begins with the
 specified text to its primary output stream.
 
 SECONDARY OUTPUT STREAM:  If its secondary output stream is connected, FIND
 copies each input record that does not begin with the specified text to its
 secondary output stream.
 

Examples

 
 

Example 1

The 'df' command returns a heading line followed by one line of information for each filesystem on linux/aix machine. Each line begins with the filesystem name. To display a line of information for only filesystem '/dev/sda9', enter the following command: pipe "command df!find /dev/sda9! console"

Example 2

To write all lines of file PROG1.ASSEMBLE that begin with an asterisk (*) to file COMMENTS.FILE and to write all other lines to file CODE.FILE, use the following exec procedure: pipe "(end ?) < PROG1.ASSEMBLE ! a:find *! > COMMENTS.FILE ? a: ! > CODE.FILE" ¤ (end ?) assigns ? as the pipeline end character. ¤ < PROG1.ASSEMBLE reads the file PROG1.ASSEMBLE into the pipeline. ¤ a:find * defines a label a for the FIND stage. FIND writes all input records that begin with an asterisk (*) to its primary output stream. ¤ > COMMENTS.FILE receives the records from the FIND stage's primary output stream and writes them to the file COMMENTS.FILE. It is the last stage in the first pipeline. ¤ ? marks the end of the first pipeline and the beginning of the second pipeline. ¤ a: references the label on the FIND stage in the first pipeline and defines the secondary output stream for FIND. FIND writes all input records that do not begin with an asterisk (*) to its secondary output stream. ¤ > CODE.FILE writes the FIND stage's secondary output stream to the file CODE.FILE.

Stage: LOCATE


Syntax

 
 
               .-- 1-* ---------------------------------------------.
 >>-- Locate --+----------------------------------------------------+------------>
               '-.--| Separator |--| Inputrange |----------------.--'
                 |                                               |
                 |      <---------------------------------<      |     (1) 
                 '-- ( ----| Separator |--| Inputrange |---- ) --'
 
 >--.----------------.----------------------------------------><
    |-- /string/ ----|
    |-- Xhexstring --|
    |-- Hhexstring --|
    '-- Bbinstring --'
 
 Separator:
 |--.------------------------------------------.-----------------------|
    '--.-- WORDSEParator ---.--.-- char -----.-'
       |-- WS --------------|  |-- hexchar --|
       |-- FIELDSEparator --|  |-- BLANK ----|
       '-- FS --------------'  '-- SPACE ----'
 
 Inputrange:
            (2)
 |--.-- Words ------- wnumberrange ----.-------------------------------|
    |        (2)                       |
    |-- Fields ------- fnumberrange ---|
    '-- cnumberrange ------------------'
 
 Notes:
 (1)  You can specify a maximum of 10 Inputranges, each separated by a blank.
 
 (2)  Blanks are optional in this position.
 
 

Purpose

 
 Use the LOCATE stage command to select records that contain a specified target
 string of characters.  LOCATE writes primary input stream records that contain
 a specified string to its primary output stream, if it is connected.  If its
 secondary output stream is connected, LOCATE writes all other input records to
 its secondary output stream.  If you do not specify a string, a null string is
 assumed.
 
 LOCATE searches for the specified string within one or more specified
 locations of the input data in the record.  If you do not specify a location,
 LOCATE searches the entire input record.  When at least one input data
 location is specified, if you do not specify a string or you specify a null
 string, LOCATE writes to its primary output stream only input records of
 length x or greater, where x is the input data location with the smallest
 absolute value.
 
 When LOCATE is used to search for a string, uppercase and lowercase
 representations of the same characters do not match.  A match is found only if
 the data in the input records matches the target string you specify, including
 blank characters.  Blank characters contained in the input stream must match
 the blank characters specified in the target string.
 
 

Operands

 
 WORDSEParator
 WS
     specifies the character that is used to separate words in the input
     records.  For example, use WORDSEPARATOR to specify that the dash
     separates each word:
 
       pipe "literal a-b-c ! literal d-e-f ! locate wordsep - w3 /c/ ! console" 
       a-b-c
 
     If WORDSEPARATOR (or WS) is specified more than once in a LOCATE stage, a
     word separator character remains in effect until the next WORDSEPARATOR
     (or WS) specification is encountered.
 
     A blank is used as the default for WORDSEPARATOR (or WS).
 
 FIELDSEparator
 FS
     specifies the character that is used to separate fields in the input
     records.  For example, use FIELDSEP to specify that the question mark
     separates each field:
 
       pipe "literal a?b? ! literal e??f ! locate fieldsep ? f2-3 /f/ ! console" 
       e??f
 
     If FIELDSEPARATOR (or FS) is specified more than once in a LOCATE stage, a
     field separator character remains in effect until the next FIELDSEPARATOR
     (or FS) specification is encountered.
 
     X'05' is the default field separator character.
 
 char
 hexchar
     is the single character, char, or the 2-character hexadecimal
     representation of a character, hexchar.  Do not enclose the hexadecimal
     representation in quotation marks.
 
     Use char or hexchar with:
 
       o WORDSEPARATOR (or WS) to specify the word separator character.
 
       o FIELDSEPARATOR (or FS) to specify the field separator character.
 
 BLANK
 SPACE
     specifies that a blank is used as the:
 
       o Word separator character when specified with the WORDSEPARATOR (or WS)
         operand.
 
       o Field separator character when specified with the FIELDSEPARATOR (or
         FS) operand.
 
 Words
     specifies, in terms of delimited character strings (words), the input data
     on which the LOCATE stage command operates.  The WORDSEPARATOR (or WS)
     operand defines the character that delimits words.  For example, the input
     character string in the following PIPE command consists of two records
     with three words each where the words are separated by a blank:
 
       pipe "literal aj cd ej ! literal gh ij kl ! locate word 2 /j/ ! console" 
       gh ij kl
 
     A word cannot be null.  If a record begins with one or more delimiters,
     the first word in that record begins in the position immediately following
     the delimiter or delimiters.  Two or more consecutive delimiters are
     equivalent to having one delimiter which means that the next word begins
     in the first position after the delimiters.  In the following example, for
     both records, ab is the first word and a is the third word:
 
       pipe "literal ?ab?c??a ab?c?a| split | locate (ws ? w1 w3) /a/| console " 
       ?ab?c??a
       ab?c?a
 
 Fields
     specifies, in terms of delimited fields, the input data on which the
     LOCATE stage command operates.  The FIELDSEPARATOR (or FS) operand defines
     the character that delimits fields.
 
     In the following example, the input data contains two records each with
     two fields separated by a dash (-):
 
       pipe "literal a b-c d |literal  c f-g h | locate fs - f2 /c/ |console " 
       a b-c d
 
     A field can be null.  A record that begins with the delimiter has a null
     field as the first field.  Two consecutive delimiters is considered a null
     field.  The following example shows both types of null fields:
 
       pipe "literal ?ab?c??a ab?c?a| split | locate (fs ? f1 f3) /a/ | console" 
       ab?c?a
 
 wnumberrange
 fnumberrange
 cnumberrange
     defines a specified location of the input data as a range of word numbers,
     field numbers, or column numbers on which LOCATE operates.  The location
     is relative to the beginning or the end of the record.  A negative number
     in the range indicates that the range is relative to the end of the
     record; otherwise, the range is relative to the beginning of the record.
     If you do not specify a location, LOCATE searches the entire input record
     for occurrences of string, hexstring, or binstring.  You can specify a
     location as follows:
 
     location
     -location
         is a single column number, word number, or field number.  -location is
         relative to the end of the record.  The last location in the record is
         -1.
 
     location1-location2
     location1;location2
     -location1;location2
     location1;-location2
     -location1;-location2
         is a range of columns, words, or fields beginning with location1 and
         ending with location2, inclusive.  If you specify both locations
         relative to the beginning of the input record, (that is, you use
         location1 and location2), location2 must be numerically equal to or
         greater than location1.  If you specify both locations relative to the
         end of the input record, (that is, you use -location1 and -location2),
         location2 must be numerically less than or equal to location1.  For
         example, the following PIPE command specifies the next-to-last and the
         last column as the input location:
 
           pipe "literal afbc adef ghfi fjkl| split | locate -2;-1 /f/ | console" 
           adef
           ghfi
 
         If you specified WORDS or FIELDS, -2;-1 specifies that the
         second-from-last word or field and the last word or field is the input
         location.
 
         If you specify location1;-location2 or if you specify
         -location1;location2, the position in the record defined by location1
         must occur before the position in the record defined by location2.
         For example, no positions in the input record to LOCATE are searched
         if you specify -8;6 for an input record that contains 15 columns since
         location1 is positioned after location2 in the record.
 
     location1-*
     location1;*
     -location1;*
         is a range of columns, words, or fields beginning with location1 and
         ending with the last column, word, or field of the record, inclusive.
 
     *-location2
     *;location2
     *;-location2
         is a range of columns, words, or fields beginning with the first
         column, word, or field of the record and ending with location2,
         inclusive.
 
     *-*
     *;*
         is a range of columns, words, or fields beginning with the first
         column, word, or field of the record and ending with the last column,
         word, or field of the record, inclusive.
 
     location1.n
         is a range of n columns, words, or fields beginning with location1.
         You can specify any number from 1 to 2(31) -1 for n.
 
 /(diagonal)
     signifies any nonblank delimiting character that does not appear in
     string.  If no operands are specified before string and if string consists
     of only decimal numbers (0-9), you cannot specify a left parenthesis or a
     number as the delimiting character.  See Usage Note 3 for an example.
 
     You cannot use a B, b, X, x, H, h, or ( for a delimiting character.
 
 string
     defines a target string of characters to be located.
 
 Xhexstring
 Hhexstring
     defines a target string of hexadecimal characters, following the X or H,
     that defines a target string of characters to be located.  The X or H can
     be specified in uppercase or lowercase.  You must not specify any spaces
     in the string.  There must be an even number of hexadecimal characters in
     the string.
 
 Bbinstring
     defines a string of 0's and 1's, following the B, that defines a target
     string of characters to be located.  The B can be specified in uppercase
     or lowercase.  You must not specify any spaces in the string.  The number
     of binary digits must be divisible by 8.

Streams

 
 
 PRIMARY INPUT STREAM:  LOCATE reads records from its primary input stream.
 
 PRIMARY OUTPUT STREAM:  If the target string is specified, LOCATE copies input
 records that contain the target string within any specified column range, word
 range, or field range to its primary output stream.  If the target string is
 not specified and cnumberrange, wnumberrange, or fnumberrange is specified,
 LOCATE writes to its primary output stream only input records of length x or
 greater, where x is the input data location with the smallest absolute value.
 
 SECONDARY OUTPUT STREAM:  If its secondary output stream is connected, LOCATE
 copies each input record that is not written to its primary output stream to
 its secondary output stream.

Examples

Example 1

The Linux df command displays information similar to the following: df Filesystem 1k-blocks Used Available Use% Mounted on /dev/sda1 1225396 918304 244844 79% / /dev/sda7 101089 41963 53907 44% /home /dev/sda9 54416 15729 35878 30% /tmp /dev/sda5 497829 32 472095 0% /usr/local /dev/sda8 54416 11082 40525 21% /var One line of information is displayed for each filesystem you have. To display information about sda7, enter the following command: pipe "command df ! locate /sda7/ ! console"

Example 2

Given the input file containing student grade information, use the following command to display only the lines about students who received a grade of 100 on exam 2 or exam 3. pipe "< STUDENT.GRADES ! locate (30-32 40-42) /100/ ! console" STUDENT.GRADES
STUDENT           EXAM 1    EXAM 2    EXAM 3    EXAM 4
 
CAROLYN             78        87       100        95
EVELYN              85        84        82        89
JACK               100        89        89       100
KEN                 88        79        79        93
KAREN               90       100       100        95
MICHAEL             87       100        99       100
Results
                                               
pipe "< STUDENT.GRADES ! locate (30-32 40-42) /100/ ! console" 
CAROLYN             78        87       100        95
KAREN               90       100       100        95
MICHAEL             87       100        99       100

Example 3

To display only those lines of file FLAG.COLORS that contain both the string, RED, and the string, WHITE, enter: pipe " < FLAG.COLORS ! locate /RED/ ! locate /WHITE/ ! console" The first LOCATE stage writes all records containing RED to its primary output stream. The second LOCATE stage then reads those records and selects only the records that also contain WHITE to write to its primary output stream.

Example 4

To display only those lines of file ALPHA.SCRIPT that are 10 or more characters in length, enter the following command: pipe " < ALPHA.SCRIPT ! locate 10 ! console" Because no string is specified on the LOCATE stage command, only records with 10 or more characters are written to the output stream.

Example 5

To display only those lines of file FLAG.COLORS that contain either the string, RED, or the string, WHITE, use the following pipeline command procedure:
(endchar ?)
  < FLAG.COLORS      # read FLAG.COLORS
! a:locate /RED/     # find records containing RED
! b:faninany         # get records containing RED or WHITE
! console            # display records at terminal
  ?                  # start of second pipeline
  a:                 # define secondary output for LOCATE /RED/
! locate /WHITE/     # find records containing WHITE
! b:                 # define secondary input for FANINANY
¤ (endchar ?) assigns ? as the pipeline end character. ¤ < FLAG.COLORS reads file FLAG.COLORS into the pipeline. ¤ a:locate /RED/ defines a label a for the LOCATE stage. LOCATE writes all records containing RED to its primary output stream. ¤ b:faninany defines a label b for the FANINANY stage. FANINANY reads the records from its primary and secondary input streams and writes them to its primary output stream. ¤ console writes the records to the terminal. It is the last stage in the first pipeline. ¤ ? marks the end of the first pipeline and the beginning of the second pipeline. ¤ a: references the label on the LOCATE stage in the first pipeline and defines the secondary output stream for that LOCATE stage. LOCATE writes all records not containing RED to its secondary output stream. ¤ locate /WHITE/ writes all records containing WHITE to its primary output stream. All other records are discarded because no secondary output stream is defined for this stage. ¤ b: references the label on the FANINANY stage in the first pipeline and defines the secondary input stream for the FANINANY stage.

Stage: NFIND


Syntax

 
 
 >>--- NFIND --.----------.---------------------------------><
               '-- text --'
 

Purpose

(purpose not available)

Operands

 
 
 text
     is any text that you want to NOT find, beginning in the first column of an
     input record.  Each character in text must exactly match the corresponding
     character in the input record.
 
     Uppercase and lowercase representations of the same alphabetic character
     do not match.  To be selected, an input record must be at least as long as
     text, including any trailing blanks specified in text.
 

Streams

 PRIMARY INPUT STREAM:  NFIND reads records from its primary input stream.
 
 PRIMARY OUTPUT STREAM:  NFIND copies each input record that does not begin with the
 specified text to its primary output stream.
 
 SECONDARY OUTPUT STREAM:  If its secondary output stream is connected, NFIND
 copies each input record that begins with the specified text to its
 secondary output stream.
 

Examples

 
 
same as FIND stage...except invert primary and secondary output stream !
 

Stage: NLOCATE


Syntax

 
 
               .-- 1-* ---------------------------------------------.
 >>- NLocate --+----------------------------------------------------+------------>
               '-.--| Separator |--| Inputrange |----------------.--'
                 |                                               |
                 |      <---------------------------------<      |     (1) 
                 '-- ( ----| Separator |--| Inputrange |---- ) --'
 
 >--.----------------.----------------------------------------><
    |-- /string/ ----|
    |-- Xhexstring --|
    |-- Hhexstring --|
    '-- Bbinstring --'
 
 Separator:
 |--.------------------------------------------.-----------------------|
    '--.-- WORDSEParator ---.--.-- char -----.-'
       |-- WS --------------|  |-- hexchar --|
       |-- FIELDSEparator --|  |-- BLANK ----|
       '-- FS --------------'  '-- SPACE ----'
 
 Inputrange:
            (2)
 |--.-- Words ------- wnumberrange ----.-------------------------------|
    |        (2)                       |
    |-- Fields ------- fnumberrange ---|
    '-- cnumberrange ------------------'
 
 Notes:
 (1)  You can specify a maximum of 10 Inputranges, each separated by a blank.
 
 (2)  Blanks are optional in this position.
 
 

Purpose

 
 Use the NLOCATE stage command to not select records that contain a specified target
 string of characters.  NLOCATE writes primary input stream records that do not contain
 a specified string to its primary output stream, if it is connected.  If its
 secondary output stream is connected, NLOCATE writes all other input records to
 its secondary output stream.  If you do not specify a string, a null string is
 assumed.
 
 
 

Operands

 
 see LOCATE stage 
 

Streams

 
 
 PRIMARY INPUT STREAM:  NLOCATE reads records from its primary input stream.
 
 PRIMARY OUTPUT STREAM:  If the target string is specified, NLOCATE copies input
 records that do not contain the target string within any specified column range, word
 range, or field range to its primary output stream.  If the target string is
 not specified and cnumberrange, wnumberrange, or fnumberrange is specified,
 NLOCATE writes to its primary output stream only input records of length less that x
 , where x is the input data location with the smallest absolute value.
 
 SECONDARY OUTPUT STREAM:  If its secondary output stream is connected, NLOCATE
 copies each input record that is not written to its primary output stream to
 its secondary output stream.

Examples

see LOCATE examples and change primary and secondary output streams.
 
 

Stage: BETWEEN


Syntax

 >>-- BETWEEN ---.---------------.---.-- /string1/ ----.---.-- /string2/ ----.----><
                 '--- ANYcase ---'   |-- Xhexstring1 --|   |-- Xhexstring2 --|
                                     |-- Hhexstring1 --|   |-- Hhexstring2 --|
                                     '-- Bbinstring1 --'   |-- Bbinstring2 --|
                                                           '-- n-------------'
 

Purpose

 Use the BETWEEN stage command to select groups of records from its primary
 input stream, starting with the first record that begins with a specified
 target string.  BETWEEN writes a group or records to its primary output
 stream, if connected, ending a group with the record that has the second
 specified string or with all remaining records once the specified number of
 records that won't be selected is reached.  Each specified target string must
 begin in the first column of an input record.
 
 If the secondary output stream is connected, BETWEEN writes the records that
 are not selected to its secondary output stream.  If the secondary output
 stream is not connected, BETWEEN discards these records.
 
 Uppercase and lowercase representations of the same characters do not match,
 except if ANYcase is indicated!
 A match is found only if the data in the input records exactly matches the
 target strings you specify, including blank characters.  Blank characters
 contained in the input stream must match the blank characters in the target
 strings.
 

Operands

 /(diagonal)
     signifies any nonblank delimiting character that does not appear in the
     string it delimits.
 
     You do not have to use the same delimiter character for string1 and
     string2.  For example,
 
       BETWEEN /abc/ ?def?
 
     is the same as
 
       BETWEEN /abc/ /def/
 
     If string2 is specified and it consists of only decimal numbers (0-9), you
     cannot specify a number as the delimiting character.  See Usage Note 3 for
     an example.
 
     You cannot use a B, b, X, x, H, or h for a delimiting character.
 
 string1
 string2
     defines the starting target string of characters to be located (string1)
     and the ending target string of characters to be located (string2).  Both
     target strings must begin in the first column of an input record.
 
 Xhexstring1
 Hhexstring1
 Xhexstring2
 Hhexstring2
     specifies a string of hexadecimal characters, following the X or H, that
     defines the starting (hexstring1) and ending (hexstring2) target string of
     characters to be located.  The X or H can be specified in uppercase or
     lowercase.  You must not specify any spaces in the string.  There must be
     an even number of hexadecimal characters in the string.  Both target
     strings must begin in the first column of an input record.
 
 Bbinstring1
 Bbinstring2
     specifies a string of 0's and 1's, following the B, that defines the
     starting string of characters to be located (binstring1) and the ending
     target string of characters to be located (binstring2).  The B can be
     specified in uppercase or lowercase.  You must not specify any spaces in
     the string.  The number of binary digits must be divisible by 8.  Both
     target strings must begin in the first column of an input record.
 
 n
     specifies the number of records to be written to the primary output
     stream, starting with and including the record that begins with the
     starting target string1.  BETWEEN writes n records each time the starting
     target string is found in the first column of an input record.  n cannot
     be less than 2.  If the number of records remaining in the input stream is
     less than n, the remaining records are written to the primary output
     stream.
 
 ANYcase
	  Implies matching will be done case insensitive.

Streams

 PRIMARY INPUT STREAM:  BETWEEN reads records from its primary input stream.
 
 PRIMARY OUTPUT STREAM:   BETWEEN writes to its primary output stream input
 records that begin with the specified target string and all records up to and
 including the record with the second specified target string or up to and
 including the record corresponding to the number specified.
 
 SECONDARY OUTPUT STREAM:  If its secondary output stream is connected, BETWEEN
 writes all input records not selected to its secondary output stream.

Examples

 Example 1:
        After issuing the following PIPE command:
 
          pipe "< abc.script ! between /ccc/ /rrr/ ! console " 
 
        the contents of the primary input stream (which is the data from the
        file abc.script), the primary output stream, and the secondary output
        stream are:
 
 
                                         PRIMARY OUTPUT STREAM
                              +-----+    +--------------+
        PRIMARY INPUT STREAM  |     |--->| cccddd       |
        +--------------+      |  B  |    | dddeee       |
        | aaabbb       |      |  E  |    | eeefff       |
        | bbbccc       |      |  T  |    +--------------+
        | aaabbb       |----->|  W  |
        | cccddd       |      |  E  |    SECONDARY OUTPUT STREAM
        | dddeee       |      |  E  |    +--------------+
        | eeefff       |      |  N  |--->| aaabbb       |
        +--------------+      |     |    | bbbccc       |
                              +-----+    | aaabbb       |
                                         +--------------+
 
 Example 2:
 	To select all the examples in a file called 'rexx.script', assuming each example
 	is delimited by a record that begins with :xmp. and a record that begins with
 	:exmp., and to write them to a file called 'rexx.examples', use the following
 	PIPE command:
 	
 	 pipe " < rexx.script ! between /:xmp./ /:exmp./ ! > rexx.examples " 
 	
 	Figure 1 and Figure 2 show the contents of the input file rexx.script and the
 	resulting output file rexx.examples after execution of the previous PIPE
 	command.
 	
 	 rexx.script
 	
 	===== * * * Top of File * * *
 	===== To display a line of text on a terminal, use the SAY statement.
 	===== For example,
 	===== :xmp.
 	===== /* EXAMPLE OF THE SAY STATEMENT */
 	===== say 'What is your first name?'
 	===== pull name .
 	===== say 'Hello,' name'!'
 	===== exit
 	===== :exmp.
 	===== To determine the length of a character string, use the LENGTH
 	===== function.  For example,
 	===== :xmp.
 	===== /* EXAMPLE OF THE LENGTH FUNCTION */
 	===== say 'What is your first name?'
 	===== pull name .
 	===== namelen=length(name)
 	===== say 'Your first name contains' namelen 'characters.'
 	===== exit
 	===== :exmp.
 	===== * * End of File * * *
 	
 	Figure 1. BETWEEN Stage Command Example: Input File Contents
 	
 	 rexx.examples
 	
 	===== * * * Top of File * * *
 	===== :xmp.
 	===== /* EXAMPLE OF THE SAY STATEMENT */
 	===== say 'What is your first name?'
 	===== pull name .
 	===== say 'Hello,' name'!'
 	===== exit
 	===== :exmp.
 	===== :xmp.
 	===== /* EXAMPLE OF THE LENGTH FUNCTION */
 	===== say 'What is your first name?'
 	===== pull name .
 	===== namelen=length(name)
 	===== say 'Your first name contains' namelen 'characters.'
 	===== exit
 	===== :exmp.
 	===== * * * End of File * * *
 	
 	Figure 2. BETWEEN Stage Command Example: Output File Contents		
 
 Example 1 in runcases:

Results
pipe "(end ?)literal aaabbb bbbccc aaabbb cccddd dddeee eeefff!split!b:between /ccc/ /rrr/! cons 0 ? b: ! cons 1 "
Console(1):aaabbb
Console(1):bbbccc
Console(1):aaabbb
Console(0):cccddd
Console(0):dddeee
Console(0):eeefff	

Stage: DROP


Syntax

 
             .-- FIRST --.  .-- 1 --.
 >>-- DROP --+-----------+--+-------+------.-------------.-------------><
             '-- LAST ---'  |-- n --|      '--- BYTES ---'
                            '-- * --'
 
 

Purpose

 Use the DROP stage command to discard one or more records at the beginning or
 end of its primary input stream.  DROP selects the remaining records, copying
 them to its primary output stream, if it is connected.  If its secondary
 output stream is connected, DROP passes any unselected records to its
 secondary output stream.
 If you specify BYTES, use term 'characters' instead of 'records' in the above explanation.

Operands

 
 FIRST
     discards records from the beginning of the input stream.  This is the
     default.
 
 LAST
     selects records until only the specified number remain, and discards the
     last specified number of records from the end of the input stream.
 
 n
     is the number of records to discard from the input stream.  The default is
     1.  If you specify 0 for n, all records in the primary input stream are
     selected and copied unchanged to the primary output stream.
 
 *
     specifies that no records are selected.  These are passed to the secondary
     output stream if it is connected, otherwise, DROP discards all records.
 
 BYTES
     bytes are counted instead of records.
     So, you can get truncated records, because with this option DROP can or not
     spill records, depending on the specified number n.

Streams

 
 PRIMARY INPUT STREAM:  DROP reads records from its primary input stream.
 
 PRIMARY OUTPUT STREAM:   Any records that are not dropped are copied to the
 primary output stream, if it is connected.
 
 SECONDARY OUTPUT STREAM:  DROP passes any unselected records to its secondary
 output stream, if it is connected.

Examples

 

Example 1

To drop the two first lines of the file autoexec.bat: pipe "< c:\autoexec.bat ! drop 2 ! console"

Example 2

To drop the last 3 lines of file 'xxx.yyy' and keep them in a 'toto' file pipe "(end ?) < xxx.yyy!d:drop last 3 ! console ? d: ! > toto"

Example 3

To drop the first 5 lines and display the others: pipe "apl {iota} 10!split!drop 5! console" where: apl {iota} 10 generates: 1 2 3 4 5 6 7 8 9 10 split splits words, one per line drop 5 drops the first 5 lines (so 1,2,3,4,5) Results
pipe "apl {iota} 10!split!drop 5! console"
6
7
8
9
10
sample with option LAST Results
pipe "apl {iota} 10!split!drop last 5! console"
1
2
3
4
5

Stage: FRLABEL


Syntax

 
 >>--.-- FRLABel ---.--.------------.----------------------------><
     '-- FROMLABel--'  '-- string --'
 
 

Purpose

 Use the FRLABEL stage command to select records from its primary input stream.
 The records selected are determined by the target string you specify.  The
 specified target string must begin in the first column of an input record.
 Once a record that begins with the target string is found, the record that
 begins with the target string and the following records are shorted to the
 primary output stream.
 
 If the secondary output stream is connected, FRLABEL writes the records that
 are before the record that begins with the target string to its secondary
 output stream.  If the secondary output stream is not connected, FRLABEL
 discards these records.
 
 Uppercase and lowercase representations of the same characters do not match.
 A match is found only if the data in the input records exactly matches the
 target strings you specify, including blank characters.  Blank characters
 contained in the input stream must match the blank characters specified in the
 target strings.

Operands

 
 string
     defines the string of characters to be located in the first column of an
     input record.  If string is not specified, FRLABEL copies all input
     records to its primary output stream.

Streams

 PRIMARY INPUT STREAM:  FRLABEL reads records from its primary input stream.
 
 PRIMARY OUTPUT STREAM:  FRLABEL copies the first input record that begins with
 the specified target to its primary output stream.  All remaining input stream
 records are then copied to its primary output stream.
 
 SECONDARY OUTPUT STREAM:  If its secondary output stream is connected, FRLABEL
 copies all input records up to but not including the first record matching the
 specified search string to its secondary output stream.  FRLABEL copies the
 remaining records that do match the specified string to its primary output
 stream.
 

Examples

 
 To select all the names in a phone directory file, called PHONE.DIR, that
 begin with the letter P through the end of the alphabet and to write these
 records to a file called PHONE.P-Z), use the following PIPE command:
 
   pipe "< PHONE.DIR ! frlabel P! > PHONE.P-Z" 
 
 Below are contents of input file and result to console.
 

PHONE.DIR
Andrews, Joe       30   555-214-5435
Brown, Sue         28   555-413-3423
C
D
E
F
G
H
I
Jones, Fred        50   607-413-8945
K
L
Mills, Bob         23   555-212-2122
N
O
P
Q
R
Smith, Elaine      45   243-313-4277
Smith, Joe         24   234-315-2342
Smith, Sue         33   543-314-0087
T
U
V
W
X
Y
Zimmer, Jack       39   607-917-8754
Results
pipe "< PHONE.DIR ! frlabel P! console"
P
Q
R
Smith, Elaine      45   243-313-4277
Smith, Joe         24   234-315-2342
Smith, Sue         33   543-314-0087
T
U
V
W
X
Y
Zimmer, Jack       39   607-917-8754

Stage: FROMLABEL


Syntax

 
 >>--.-- FRLABel ---.--.------------.----------------------------><
     '-- FROMLABel--'  '-- string --'
 
 

Purpose

 Use the FRLABEL stage command to select records from its primary input stream.
 The records selected are determined by the target string you specify.  The
 specified target string must begin in the first column of an input record.
 Once a record that begins with the target string is found, the record that
 begins with the target string and the following records are shorted to the
 primary output stream.
 
 If the secondary output stream is connected, FRLABEL writes the records that
 are before the record that begins with the target string to its secondary
 output stream.  If the secondary output stream is not connected, FRLABEL
 discards these records.
 
 Uppercase and lowercase representations of the same characters do not match.
 A match is found only if the data in the input records exactly matches the
 target strings you specify, including blank characters.  Blank characters
 contained in the input stream must match the blank characters specified in the
 target strings.

Operands

 
 string
     defines the string of characters to be located in the first column of an
     input record.  If string is not specified, FRLABEL copies all input
     records to its primary output stream.

Streams

 PRIMARY INPUT STREAM:  FRLABEL reads records from its primary input stream.
 
 PRIMARY OUTPUT STREAM:  FRLABEL copies the first input record that begins with
 the specified target to its primary output stream.  All remaining input stream
 records are then copied to its primary output stream.
 
 SECONDARY OUTPUT STREAM:  If its secondary output stream is connected, FRLABEL
 copies all input records up to but not including the first record matching the
 specified search string to its secondary output stream.  FRLABEL copies the
 remaining records that do match the specified string to its primary output
 stream.
 

Examples

 
 To select all the names in a phone directory file, called PHONE.DIR, that
 begin with the letter P through the end of the alphabet and to write these
 records to a file called PHONE.P-Z), use the following PIPE command:
 
   pipe "< PHONE.DIR ! frlabel P! > PHONE.P-Z" 
 
 Below are contents of input file and result to console.
 

PHONE.DIR
Andrews, Joe       30   555-214-5435
Brown, Sue         28   555-413-3423
C
D
E
F
G
H
I
Jones, Fred        50   607-413-8945
K
L
Mills, Bob         23   555-212-2122
N
O
P
Q
R
Smith, Elaine      45   243-313-4277
Smith, Joe         24   234-315-2342
Smith, Sue         33   543-314-0087
T
U
V
W
X
Y
Zimmer, Jack       39   607-917-8754
Results
pipe "< PHONE.DIR ! frlabel P! console"
P
Q
R
Smith, Elaine      45   243-313-4277
Smith, Joe         24   234-315-2342
Smith, Sue         33   543-314-0087
T
U
V
W
X
Y
Zimmer, Jack       39   607-917-8754

Stage: INSIDE


Syntax

 >>-- INSIDE ----.---------------.---.-- /string1/ ----.---.-- /string2/ ----.----><
                 '--- ANYcase ---'   |-- Xhexstring1 --|   |-- Xhexstring2 --|
                                     |-- Hhexstring1 --|   |-- Hhexstring2 --|
                                     '-- Bbinstring1 --'   |-- Bbinstring2 --|
                                                           '-- n-------------'
 

Purpose

 Use the INSIDE stage command to select groups of records from its primary
 input stream, starting with the first record following the record that begins
 with a specified string.  INSIDE writes a group of records to its primary
 output stream, if connected, ending a group just prior to the record that has
 the second specified string or the record corresponding to the number
 specified.  Each specified target string must begin in the first column of an
 input record.
 
 If the secondary output stream is connected, INSIDE writes the records that
 are not selected to its secondary output stream.  If the secondary output
 stream is not connected, INSIDE discards these records.
 
 Uppercase and lowercase representations of the same characters do not match
 except if ANYcase is specified.
 

Operands

 
 /(diagonal)
     signifies any nonblank delimiting character that does not appear in the
     string it delimits.
 
     You do not have to use the same delimiter character for string1 and
     string2.  For example,
 
       INSIDE /abc/ ?def?
 
     is the same as
 
       INSIDE /abc/ /def/
 
     If string2 is specified and it consists of only decimal numbers (0-9), you
     cannot specify a number as the delimiting character.  See Usage Note 3 for
     an example.
 
     You cannot use a B, b, X, x, H, or h for a delimiting character.
 
 string1
 string2
     defines the starting target string of characters to be located (string1)
     and the ending target string of characters to be located (string2).  Both
     target strings must begin in the first column of an input record.  A null
     string matches any record.
 
 Xhexstring1
 Hhexstring1
 Xhexstring2
 Hhexstring2
     specifies a string of hexadecimal characters, following the X or H, that
     defines the starting (hexstring1) and ending (hexstring2) target string of
     characters to be located.  The X or H can be specified in uppercase or
     lowercase.  You must not specify any spaces in the string.  There must be
     an even number of hexadecimal characters in the string.  Both target
     strings must begin in the first column of an input record.
 
 Bbinstring1
 Bbinstring2
     specifies a string of 0's and 1's, following the B, that defines the
     starting string of characters to be located (binstring1) and the ending
     target string of characters to be located (binstring2).  The B can be
     specified in uppercase or lowercase.  You must not specify any spaces in
     the string.  The number of binary digits must be divisible by 8.  Both
     target strings must begin in the first column of an input record.
 
 n
     specifies the number of records to be written to the primary output
     stream, starting with the record immediately following the record that
     begins with the target string1.  INSIDE writes n records each time string1
     is found in the first column of an input record.  n must be 0 or greater.
     If the number of records remaining in the input stream is less than n, the
     remaining records are written to the primary output stream.
 
 ANYcase
	  Implies matching will be done case insensitive.

Streams

 PRIMARY INPUT STREAM:  INSIDE reads records from its primary input stream.
 
 PRIMARY OUTPUT STREAM:   INSIDE writes to its primary output stream input
 records that begin just after the specified target string and all records up to and
 excluding the record with the second specified target string or up to and
 including the record corresponding to the number specified.
 
 SECONDARY OUTPUT STREAM:  If its secondary output stream is connected, INSIDE
 writes all input records not selected to its secondary output stream.

Examples

Example 1

After issuing the following PIPE command: pipe "< INSIDE1 ! inside /ccc/ /rrr/ ! console " the contents of the primary input stream (which is the data from the file INSIDE1), the primary output stream, and the secondary output stream are: PRIMARY OUTPUT STREAM *-----* *--------------* PRIMARY INPUT STREAM | |--->| dddeee | *--------------* | I | | eeefff | | aaabbb | | N | *--------------* | bbbccc | | S | | aaabbb |----->| I | SECONDARY OUTPUT STREAM | cccddd | | D | *--------------* | dddeee | | E |--->| aaabbb | | eeefff | | | | bbbccc | *--------------* | | | aaabbb | *-----* | cccddd | *--------------* INSIDE1
aaabbb
bbbccc
aaabbb
cccddd
dddeee
eeefff
Results
                                               
pipe "< INSIDE1 ! inside /ccc/ /rrr/ ! console "
dddeee
eeefff

Example 2

To select all the examples in a file called 'INSIDE2', assuming each example is delimited by a record that begins with :xmp. and a record that begins with :exmp., and to write them to the console, use the following PIPE command: pipe " < INSIDE2 ! inside /:xmp./ /:exmp./ ! console " Following figures show the contents of the input file INSIDE2 and the resulting output after execution of the previous PIPE command. INSIDE2
To display a line of text on a terminal, use the SAY statement.
For example,
:xmp.
/* EXAMPLE OF THE SAY STATEMENT */
say 'What is your first name?'
pull name .
say 'Hello,' name'!'
exit
:exmp.
To determine the length of a character string, use the LENGTH
function.  For example,
:xmp.
/* EXAMPLE OF THE LENGTH FUNCTION */
say 'What is your first name?'
pull name .
namelen=length(name)
say 'Your first name contains' namelen 'characters.'
exit
:exmp.
Results
pipe " < INSIDE2 ! inside /:xmp./ /:exmp./ ! console "
/* EXAMPLE OF THE SAY STATEMENT */
say 'What is your first name?'
pull name .
say 'Hello,' name'!'
exit
/* EXAMPLE OF THE LENGTH FUNCTION */
say 'What is your first name?'
pull name .
namelen=length(name)
say 'Your first name contains' namelen 'characters.'
exit

Stage: TAKE


Syntax

 
             .-- FIRST --.  .-- 1 --.
 >>-- TAKE --+-----------+--+-------+----------------------------------><
             '-- LAST ---'  |-- n --|
                            '-- * --'
 
 

Purpose

 
 Use the TAKE stage command to select one or more records from the beginning or
 end of its primary input stream.  TAKE copies the selected records to its
 primary output stream, if it is connected.  If its secondary output stream is
 connected, TAKE copies all other records to its secondary output stream,
 otherwise it discards the unselected records.
 
 

Operands


 
 FIRST
     selects records from the beginning of the input stream.  This is the
     default.
 
 LAST
     selects records from the end of the input stream.
 
 n
     is the number of records to be selected from the input stream.  The
     default is 1.  If you specify 0, TAKE copies all records to the secondary
     output stream, if it is connected, otherwise it discards all records.
 
 *
     specifies that all records are written to the primary output stream if
     connected, otherwise TAKE discards all records.

Streams

 
 PRIMARY INPUT STREAM:  TAKE reads records from its primary input stream.
 
 PRIMARY OUTPUT STREAM:  TAKE copies the selected records to its primary output
 stream, if it is connected.
 
 SECONDARY OUTPUT STREAM:   TAKE copies the unselected records to its secondary
 output stream, if it is connected.
 

Examples

Example 1

To get the last 5 records of the file autoexec.bat: pipe " < c:\autoexec.bat!take last 5!cons" Results
                                               
pipe "literal a b c d e f!split!take 3!cons " 
a
b
c
Results
                                               
pipe "literal a b c d e f!split!take last 3!cons " 
d
e
f

Stage: ?


Syntax

 
  >>--.-- HELP --.---.----------------------------------------------------.---><
      '--- ? ----'   |                       .-------- SYntax --------.   |     
                     '---.-- stagename --.---+------------------------+---'     
                         '------ * ------'   '---.--- helptype ---.---'         
                                                 '------ * -------'             
 

Purpose

 Use the HELP stage command to obtain online information about Pipelines
 stage commands.
 The HELP stage command displays or writes the following information
 to the primary output stream, if connected.

Operands

 stagename
 		is the name of a stage for which you want help.
 		If you specify *, all the core pipeline's stages are retrieved.

 helptype
		Indicate type of help documentation you want:
			SYntax  	for stage syntax (the default)
			STreams 	for stage input/output streams characteristics
			PUrpose 	for stage purpose
			OPerands 	for stage syntax operands
			EXamples    for stage examples if any...

Streams

 PRIMARY INPUT STREAM:  n/a

 PRIMARY OUTPUT STREAM:  HELP copies records to its primary output stream if connected.

Examples

Example 1

To get syntax,operands help for the specs stage, issue: ? specs

Example 2

To generate pipeline stages documentation, issue the following: ? * * ! > c:\pipestages.html Running the command generates the pipestages.html file on your disk: Results
                                               
pipe "? * * ! > pipestages.html " 
--- see pipestages.html on your disk ---

Stage: HELP


Syntax

 
  >>--.-- HELP --.---.----------------------------------------------------.---><
      '--- ? ----'   |                       .-------- SYntax --------.   |     
                     '---.-- stagename --.---+------------------------+---'     
                         '------ * ------'   '---.--- helptype ---.---'         
                                                 '------ * -------'             
 

Purpose

 Use the HELP stage command to obtain online information about Pipelines
 stage commands.
 The HELP stage command displays or writes the following information
 to the primary output stream, if connected.

Operands

 stagename
 		is the name of a stage for which you want help.
 		If you specify *, all the core pipeline's stages are retrieved.

 helptype
		Indicate type of help documentation you want:
			SYntax  	for stage syntax (the default)
			STreams 	for stage input/output streams characteristics
			PUrpose 	for stage purpose
			OPerands 	for stage syntax operands
			EXamples    for stage examples if any...

Streams

 PRIMARY INPUT STREAM:  n/a

 PRIMARY OUTPUT STREAM:  HELP copies records to its primary output stream if connected.

Examples

Example 1

To get syntax,operands help for the specs stage, issue: ? specs

Example 2

To generate pipeline stages documentation, issue the following: ? * * ! > c:\pipestages.html Running the command generates the pipestages.html file on your disk: Results
                                               
pipe "? * * ! > pipestages.html " 
--- see pipestages.html on your disk ---

Stage: QUERY


Syntax

 
 
              .-- Version --.
 >>-- Query --+-------------+-----------------------------------------------------><
              |-- Owner ----|
              |-- Stages ---|
              '-- Java -----'
 
 

Purpose

 
 Use the QUERY stage command to display at the terminal or write to its primary
 output stream, if connected, the version of Java Pipelines, the Owner (why not?),
 the list of available stages in core system and Java properties.
 
 A QUERY stage can be used only as the first stage of a pipeline.
 

Operands

 
 Version
     displays or writes the version of Java Pipelines.
 
     If the primary output stream is not connected, the message is displayed at
     the terminal.
 
     If the primary output stream is connected, the 
     message text is written to the primary output stream.
 
     Version is the default value.
 
 Owner
     displays or writes the Owner name.
 
     This purpose is only to remember owner's address if you want to contact him :o) 
 
 Stages
     displays or writes a list of the available stages in the core system.
 
 Java
     displays or writes all the Java properties.
 

Streams

 
 PRIMARY OUTPUT STREAM:  The QUERY stage command writes records containing the
 information specified by the operands to its primary output stream... 
 or to the default output if primary output stream is not connected.
 
 

Examples

Example 1

To look for stages related to command, issue the following pipe command: pipe "query stages ! locate /command/ ! cons "

Stage: RUNCASES


Syntax

 
 >>--- RUNCASES --- stage ----------------><
 
 

Purpose

 
 Use the RUNCASES to run the examples describe in onlin stage help.
 Not all of examples are structured to be run by runcases...hard work!!

Operands

(operands not available)

Streams

 
 PRIMARY INPUT STREAM:  If no parameters are given to RUNCASES, then RUNCASES
 read records from its primary input stream and process each word of reocrds
 as a stage name.
 
 PRIMARY OUTPUT STREAM:  RUNCASES writes output to its primary output if connected,
 else it writes to the default console.
 

Examples

(examples not available)

Stage: COLLATE


Syntax

 
                .-- NOPAD -----------------.
 >>-- COLLATE --+--------------------------+----| Group |----------><
                '-- PAD --.-- char -----.--'
                          |-- hexchar --|
                          |-- BLANK ----|
                          '-- SPACE ----'
 
 Group:
    .--- 1-* --- 1-* -------------------------.  .-- MASTER DETAILs --.
 |--+-----------------------------------------+--+--------------------+----|
    '-- columnrange1 ---.------------------.--'  |-- MASTER ----------|
                        '-- columnrange2 --'     |-- DETAILs ---------|
                                                 '-- DETAILs MASTER --'
 
 

Purpose

 Use the COLLATE stage command to match records in its primary input stream
 with records in its secondary input stream and write the matched and unmatched
 records to different output streams.  The records in each input stream must be
 in ascending order based on the contents of a key field.
 
 The records in the primary input stream are referred to as master records.
 Each master record has a key field, a specific range of columns within a
 record with unique contents that identifies the record; two master records
 cannot have the same contents in their key field.
 
 The records in the secondary input stream are referred to as the detail
 records.  The detail records have key fields as well, and both the master and
 detail input records should be sorted in ascending order by their key fields.
 A detail record matches a master record when the key field in both records
 contains the same data.  Two or more detail records can have the same data in
 their key field.
 
 COLLATE writes records to three output streams if each is connected:
 
   o The primary output stream contains matching records.  The operands for
     COLLATE let you specify the sequence of the master and detail records in
     the primary output stream and whether COLLATE writes both the master and
     detail records, only the master records, or only the details records to
     the primary output stream.
 
   o The secondary output stream contains master records that do not have any
     matching detail records.
 
   o The tertiary output stream contains detail records that do not have a
     matching master record.
 
The following diagram shows the input and output streams for the
COLLATE stage command using the default operands:
 
 
                            *----------*         *----------------* Primary
                            |          |-------->|Matching MASTER | Output
          *-----------*     |    C     |         | and DETAILS    | Stream
          |  MASTER   |---->|          |         *----------------*
          |           |     |    O     |
          *-----------*     |          |
          Primary Input     |    L     |
             Stream         |          |         *----------------* Secondary
                            |    L     |-------->|MASTER without  | Output
                            |          |         |matching DETAILS| Stream
                            |    A     |         *----------------*
                            |          |
          *-----------*     |    T     |
          |  DETAILS  |---->|          |
          |           |     |    E     |         *----------------* Tertiary
          *-----------*     |          |-------->|DETAILS without | Output
          Secondary Input   |          |         |matching MASTER | Stream
             Stream         *----------*         *----------------*

Operands

 NOPAD
     specifies that shorter key fields are not extended with a pad character
     before they are compared with longer key fields in other records.  This is
     the default.
 
 PAD
     specifies that shorter key fields are extended with a pad character before
     they are compared with longer key fields in other records.
 
 char
 hexchar
     is the single character, char, or the 2-character hexadecimal
     representation of a character, hexchar, used for padding.  Do not enclose
     the hexadecimal representation in quotation marks.
 
 BLANK
 SPACE
     specifies that blanks are used for padding.
 
 columnrange1
     defines a key field for the master records.  If columnrange1 is not
     specified, the key field is the entire record for both the primary and
     secondary input streams.  The format for columnrange1 is identical with
     the format for columnrange2.
 
 columnrange2
     defines a key field for the detail records.  If columnrange2 is not
     specified, columnrange1 defines the key field for both the primary and
     secondary input streams.  You can specify columnrange2 (which is identical
     with the format for columnrange1) as follows:
 
     column
         is a single column number.
 
     column1-column2
         is a range of columns beginning with column number column1 and ending
         with column number column2, inclusive.  column2 must be numerically
         equal to or greater than column1.
 
     column1-*
         is a range of columns beginning with column number column1 and ending
         with the last column of the record, inclusive.
 
     *-column2
         is a range of columns beginning with the first column of the record
         and ending with column number column2, inclusive.
 
     *-*
         is a range of columns beginning with the first column of the record
         and ending with the last column of the record, inclusive.
 
     column1.n
         is a range of n columns beginning with column number column1.  You can
         specify any number from 1 to 2(31)-1 for n.
 
 MASTER DETAILs
     specifies that for matched master and detail records, the master record
     followed by its matched detail records are written to the primary output
     stream.  This is the default.
 
 MASTER
     specifies that for matched master and detail records, only the master
     records are written to the primary output stream.  The matched detail
     records are discarded.
 
 DETAILs
     specifies that for matched master and detail records, only the detail
     records are written to the primary output stream.  The matched master
     records are discarded.
 
 DETAILs MASTER
     specifies that for matched master and detail records, the matched detail
     records followed by their master record are written to the primary output
     stream.

Streams

 PRIMARY INPUT STREAM:  COLLATE reads master records from its primary input
 stream.
 
 SECONDARY INPUT STREAM:  COLLATE reads detail records from its secondary input
 stream.  The secondary input stream must be defined.
 
 PRIMARY OUTPUT STREAM:  COLLATE writes matching records to its primary output
 stream.
 
 SECONDARY OUTPUT STREAM:  COLLATE writes master records that do not have any
 matching detail records to its secondary output stream, if it is connected.
 
 TERTIARY OUTPUT STREAM:  COLLATE writes detail records that do not have a
 matching master record to its tertiary output stream, if it is connected.

Examples

Example  
  
 In this example, COLLATE matches records from two files.  The records from the
 file BANK.INFO are the master records for the COLLATE stage, and the records
 from the file ACCOUNT.INFO are the detail records for the COLLATE stage.
 
   pipe "(end ?)< BANK.INFO ! c:collate 1-19 master detail ! > BANKACNT.INFO ? < ACCOUNT.INFO ! C:" 
 
   o (end ?) assigns ? as the pipeline end character.
 
   o < BANK.INFO reads the file BANK.INFO into the pipeline.
 
   o c: collate 1-19 master detail defines a label c for the COLLATE stage.
     COLLATE matches the records from its primary and secondary input streams
     and writes the matching master records followed by the matching detail
     records to its output stream.  Columns 1 through 19 contain the key field
     for both the primary and secondary input streams.
 
   o > BANKACNT.INFO writes the records to the file BANKACNT.INFO.  This is
     the last stage of the first pipeline.
 
   o ? marks the end of the first pipeline.
 
   o < ACCOUNT.INFO reads the file ACCOUNT.INFO into the pipeline.
 
   o c: references the label c on the COLLATE stage in the first pipeline and
     defines the secondary input stream for the COLLATE stage.  The output
     records from the preceding < stage flow to the COLLATE stage as its
     secondary input stream.
 
 Figure 1 shows the master file and Figure 2 shows the detail file.  The
 resulting output file is shown in Figure 3.  (Note that BANK.INFO and ACCOUNT.INFO
 are in ascending order by their key field, columns 1-19.)
 

BANK.INFO
Alfred, John       Account Number: 22222
Conners, Steve     Account Number: 98989
Miller, Mike       Account Number: 34567
Niles, Patrick     Account Number: 11188
Smith, Andrew      Account Number: 54545
Smith, Justin      Account Number: 77777
Williams, Janice   Account Number: 88444
Figure 1. COLLATE Stage Command Example: Input File Contents (BANK.INFO) ACCOUNT.INFO
Alfred, John       Checking            $  350.00
Alfred, John       Savings             $1,300.00
Alfred, John       Money Market        $9,000.00
Conners, Steve     Savings             $   50.00
Smith, Andrew      Savings             $1,999.00
Smith, Andrew      Money Market        $9,999.00
Smith, Justin      Checking            $     .50
Figure 2. COLLATE Stage Command Example: Input File Contents (ACCOUNT.INFO) Results
pipe "(end ?)< BANK.INFO ! c:collate 1-19 master detail ! console ? < ACCOUNT.INFO ! C:  " 
Alfred, John       Account Number: 22222
Alfred, John       Checking            $  350.00
Alfred, John       Savings             $1,300.00
Alfred, John       Money Market        $9,000.00
Conners, Steve     Account Number: 98989
Conners, Steve     Savings             $   50.00
Smith, Andrew      Account Number: 54545
Smith, Andrew      Savings             $1,999.00
Smith, Andrew      Money Market        $9,999.00
Smith, Justin      Account Number: 77777
Smith, Justin      Checking            $     .50
Figure 3. COLLATE Stage Command Example: Output File Contents

Stage: LOOKUP


Syntax

 
 
                              .-- NOPAD -----------------.
 >>-- LOOKUP --.-----------.--+--------------------------+----------------->
               '-- COUNT --'  '-- PAD --.-- char -----.--'
                                        |-- hexchar --|
                                        |-- BLANK ----|
                                        '-- SPACE ----'
 
    .-- 1-* --- 1-* ------------------------.  .-- DETAILs -- MASTER --.
 >--+---------------------------------------+--+-----------------------+----------><
    '-- columnrange1 --.------------------.-'  |-- DETAILs ------------|
                       '-- columnrange2 --'    |-- MASTER -------------|
                                               '-- MASTER -- DETAILs --'
 

Purpose

 
 Use the LOOKUP stage command to find records in a reference.
 
 LOOKUP matches records in its primary input stream with records in its
 secondary input stream and writes matched and unmatched records to different
 output streams.  The records are matched on the basis of a key field (the
 contents of a specified range of columns in the records).
 
 LOOKUP reads records from its primary and secondary input streams and writes
 records to its primary, secondary, and tertiary output streams, if each is
 connected.  The secondary input stream must be defined and connected.
 
 The records in the secondary input stream are the master records.  LOOKUP
 first reads the master records into a buffer, where records with duplicate key
 fields are discarded; the first occurrence of a key is retained.  The records
 in the buffer are referred to as the reference.
 
 The records in the primary input stream are the detail records.  LOOKUP
 compares detail records to records in the reference.
 
 LOOKUP writes records to three output streams, if each is connected:
 
   o The primary output stream contains matching records.  You can specify the
     sequence of the master and detail records written to the primary output
     stream and what is written to the primary output stream:  both detail and
     master records, only detail records, or only master records.
 
   o The secondary output stream contains detail records that do not have a
     matching master record.
 
   o The tertiary output stream contains master records in ascending order by
     their key fields.
 
 The primary and secondary output streams are severed at the end of file on the
 primary input stream before records are written to the tertiary output stream.
 
 

Operands

 
 COUNT
     specifies that each master record is prefaced with a 10-character field
     that represents the number of detail records that match the master record.
     The 10-character field is right-justified with leading blanks.
 
     If you specify COUNT and the tertiary output stream is connected, all
     master records written have a 10-character prefix that contains the number
     of matching detail records; unmatched records have a count of 0.
 
     If you do not specify COUNT and the tertiary output stream is connected,
     only unmatched master records are written.
 
 NOPAD
     specifies that shorter key fields are not extended with a pad character
     before they are compared with longer key fields in other records.  This is
     the default.
 
 PAD
     specifies that shorter key fields are extended with a pad character before
     they are compared with longer key fields in other records.
 
 char
 hexchar
     is the single character, char, or the 2-character hexadecimal
     representation of a character, hexchar, used for padding.  Do not enclose
     the hexadecimal representation in quotation marks.
 
 BLANK
 SPACE
     specifies that blanks are used for padding.
 
 columnrange1
     defines a key field for the detail records.  If columnrange1 is not
     specified, the default key field is the entire record for both the primary
     and secondary input streams.  You can specify columnrange1 as follows:
 
     column
         is a single column number.
 
     column1-column2
         is a range of columns beginning with column number column1 and ending
         with column number column2, inclusive.  column2 must be numerically
         equal to or greater than column1.
 
     column1-*
         is a range of columns beginning with column number column1 and ending
         with the last column of the record, inclusive.
 
     *-column2
         is a range of columns beginning with the first column of the record
         and ending with column2, inclusive.
 
     *-*
         is a range of columns beginning with the first column of the record
         and ending with the last column of the record, inclusive.
 
     column1.n
         is a range of n columns beginning with column number column1.  You can
         specify any number from 1 to 2(31) - 1 for n.
 
 columnrange2
     defines a key field for the master records.  If columnrange2 is not
     specified, columnrange1 defines the key field for both the primary and
     secondary input streams.  You can specify columnrange2 (which is identical
     with the format for columnrange1) as follows:
 
     column
         is a single column number.
 
     column1-column2
         is a range of columns beginning with column number column1 and ending
         with column number column2, inclusive.  column2 must be numerically
         equal to or greater than column1.
 
     column1-*
         is a range of columns beginning with column number column1 and ending
         with the last column of the record, inclusive.
 
     *-column2
         is a range of columns beginning with the first column of the record
         and ending with column2, inclusive.
 
     *-*
         is a range of columns beginning with the first column of the record
         and ending with the last column of the record, inclusive.
 
     column1.n
         is a range of n columns beginning with column number column1.  You can
         specify any number from 1 to 2(3)(1) - 1 for n.
 
 DETAILs MASTER
     specifies writing the matched detail records followed by their master
     record to the primary output stream.  This is the default.
 
 DETAILs
     specifies writing only the matched detail records to the primary output
     stream.  It discards the matched master records.
 
 MASTER
     specifies writing only the matched master records to the primary output
     stream.  It discards the matched detail records.
 
 MASTER DETAILs
     specifies writing the matched master record followed by its matched detail
     records to the primary output stream.

Streams

 
 PRIMARY INPUT STREAM:  After reaching end of file on its secondary input
 stream, LOOKUP reads detail records from its primary input stream.
 
 SECONDARY INPUT STREAM:  LOOKUP reads master records from its secondary input
 stream.  The secondary input stream must be connected.
 
 PRIMARY OUTPUT STREAM:  LOOKUP writes matching records to its primary output
 stream.
 
 SECONDARY OUTPUT STREAM:  LOOKUP writes detail records that do not have a
 matching master record to its secondary output stream, if it is connected.
 
 TERTIARY OUTPUT STREAM:  LOOKUP writes master records to its tertiary output stream,
 if it is connected.  If the COUNT operand is specified, all master records are written.
 Otherwise, only the unmatched master records are written.

Examples

Example 1

The following pipeline command finds all the records in the input file FOOD.FILE that are not in the file FRUIT.FILE: pipe "(end ?) < FOOD.FILE ! l:lookup ? < FRUIT.FILE ! l: !console" ¤ (end ?) assigns ? as the pipeline end character. ¤ < FOOD.FILE reads the file FOOD.FILE into the pipeline. ¤ l: lookup defines a label l for the LOOKUP stage. LOOKUP reads records from its secondary input stream into a buffer to serve as a reference file. It then reads the records from its primary input stream and looks each of them up in the reference. When it does not find a match in the reference, it writes the detail record from its primary input stream to its secondary output stream. (Its primary and tertiary output streams are not connected; therefore, no records are written to those streams.) ¤ ? marks the end of the first pipeline. ¤ < FRUIT.FILE reads the file FRUIT.FILE into the pipeline. ¤ l: references the label l on the LOOKUP stage in the first pipeline and defines the secondary input and output streams for LOOKUP. The records from the preceding < stage flow through this label to the LOOKUP stage as its secondary input stream. ¤ console The secondary output stream of the LOOKUP stage is connected to console that display results. FOOD.FILE
apple
orange
corn
banana
lettuce
plum
apricot
carrot
grape
pear
FRUIT.FILE
apple
banana
plum
peach
pear
pineapple
strawberry
orange
grape
watermelon
apricot
Results
                                               
pipe "(end ?) < FOOD.FILE ! l:lookup !hole? < FRUIT.FILE ! l: !cons " 
corn
lettuce
carrot

Stage: SORT


Syntax

  
                                    .-Ascending--.
 >>--SORT--.--------.---------------+------------+---------------------------><
           |-COUNT--|               |-Descending-|
           '-UNIQue-'               '-| Group |--'
 
 
 Group:
    <------------------------------------------<
                   .-Ascending--.
 |----columnrange--+------------+---------------------------------------------|
                   '-Descending-'
 

Purpose

 
 Use the SORT stage command to arrange records in ascending or descending
 order.  SORT reads records from its primary input stream and writes the
 records to its primary output stream, if it is connected.  SORT reads all
 records from its primary input stream before it writes any records to its
 primary output stream.
 
 By default, SORT compares the entire record to determine the order of records
 in its output stream.  However, you can specify one or more key fields to
 determine the sequence of records in the output stream.  A key field is a
 specific range of columns within each record.
 

Operands


 COUNT
     specifies that each record in the output stream is prefaced with a
     10-character field that represents the number of records with identical
     key fields.  The number is right-justified with leading blanks.  Records
     are considered to be identical if the specified key fields contain the
     same data.  If a key field is not specified, records are considered to be
     identical if they contain exactly the same data.
 
     When COUNT is specified, only the first record is retained; duplicate
     records are discarded.
 
 UNIQue
     writes all unique records and the first record of each set of duplicate
     records to the output stream.  Records are considered to be identical if
     the specified key fields contain the same data.  If a key field is not
     specified, records are considered to be identical if they contain the same
     data.
 
 
 Ascending
     sorts records in ascending order.  The ASCENDING operand can be specified
     in two positions on the SORT stage command:
 
       o If ASCENDING is specified and columnrange is not specified, ASCENDING
         applies to the entire record.  This is the default.
 
       o If you specify ASCENDING after columnrange, ASCENDING only applies to
         that particular key field.  This is the default.
 
 Descending
     sorts records in descending order.  The DESCENDING operand can be
     specified in two positions on the SORT stage command:
 
       o If DESCENDING is specified and columnrange is not specified,
         DESCENDING applies to the entire record.
 
       o If you specify DESCENDING after columnrange, DESCENDING only applies
         to that particular key field.
 
 columnrange
     defines a key field to sort on.  If you do not specify columnrange, the
     complete record is compared.  You can specify columnrange as follows:
 
     column
         is a single column number.
 
     column1-column2
         is a range of columns beginning with column number column1 and ending
         with column number column2, inclusive.  column2 must be numerically
         equal to or greater than column1.
 
     column1-*
         is a range of columns beginning with column number column1 and ending
         with the last column of the record, inclusive.
 
     *-column2
         is a range of columns beginning with the first column of the record
         and ending with column number column2, inclusive.
 
     *-*
         is a range of columns beginning with the first column of the record
         and ending with the last column of the record, inclusive.
 
     column1.n
         is a range of n columns beginning with column number column1.  You can
         specify any number from 1 to 2(31)-1 for n.
 
     You can specify up to ten columnrange operands.  If you specify more than
     one, you must place at least one blank between each columnrange you
     specify.
 

Streams

 
 PRIMARY INPUT STREAM:  SORT reads all records from its primary input stream
 before writing any output records.
 
 PRIMARY OUTPUT STREAM:  After sorting the records read from the input stream,
 SORT writes the records to its primary output stream.
 

Examples

Example 1

In this example, two key fields are defined; the first one in descending order and the second in ascending order (by default). The figures show the input file and the result after entering the following PIPE command: pipe "< ADDRESS.FILE ! sort 49-61 descending 34-45 ! console" ADDRESS.FILE
John M.     40 Love Court        Douglaston     New York
Arnold P.   350 Yard Drive       Pebble Beach   California
Joe F.      111 Ringside Street  Pittsburgh     Pennsylvania
Earl A.     24 Bowling Lane      Cincinnati     Ohio
Larry B.    3 Point Road         Boston         Massachusetts
Mike S.     20 Shortstop Road    Philadelphia   Pennsylvania
Joe N.      19 Jet Drive         New York       New York
Running the command displays the following output: Results
                                               
pipe "< ADDRESS.FILE ! sort 49-61 descending 34-45 ! console" 
Mike S.     20 Shortstop Road    Philadelphia   Pennsylvania
Joe F.      111 Ringside Street  Pittsburgh     Pennsylvania
Earl A.     24 Bowling Lane      Cincinnati     Ohio
John M.     40 Love Court        Douglaston     New York
Joe N.      19 Jet Drive         New York       New York
Larry B.    3 Point Road         Boston         Massachusetts
Arnold P.   350 Yard Drive       Pebble Beach   California