[Netrexx-develop] Fwd: start of new pipes documentatio

[René J. <rvj...@xs...>]

FYI, my email from the 6th of August.

> Begin forwarded message:
> 
> From: René Jansen <rvj...@xs...>
> Subject: start of new pipes documentatio
> Date: 6 August 2019 at 19:39:07 GMT-4
> To: IBM Netrexx <ibm...@hu...>
> 
> Dear NetRexx users, the following is the start of the new Pipelines documentation pertaining to NetRexx 3.08. Please have a look and see if this is usable, what isn’t clear etc. There are many topics to follow but I think this must be the start.
> 
> Configuration
> The required configuration is minimal. The NetRexxF.jar (java archive file) needs to be on the classpath (NetRexxC.jar, which is smaller, will suffice when there is a working javac compiler). Also, the current directory (.) needs to be on the CLASSPATH.
> It is convenient to have aliases or shell scripts defined as abbreviations for the invocation of the pipe, pipc (pipe compiler) and nrc (netrexx compiler) utility programs. 
> Aliases are preferable because some shell processors have idiosyncrasies in the treatment of script arguments. With an alias we can be sure that every NetRexx program sees its arguments the same way.
> .bash_aliases
> alias pipc="java org.netrexx.njpipes.pipes.compiler"
> alias pipe="java org.netrexx.njpipes.pipes.runner"
> alias nrc="java org.netrexx.process.NetRexxC"
> For Windows, the following works:
> pipe.bat
> @java org.netrexx.njpipes.pipes.runner %*
> Running pipelines
> There are a number of ways to specify and run a pipeline.
> From the command line with direct execution
> The first way is the most straightforward, and highly recognizable for users of CMS Pipelines, as it mimics the way a pipe is run in the CMS 3270 interface. The only difference is that after the PIPE command, the rest of the specification needs to be quoted in the command shells of Linux, Windows and macOS. In CMS, the pipeline specification can also be quoted - in this way, a pipeline specification can be entirely portable. Windows needs double quote, zVM/CMS does not need quotes, but if they are used they need to be double quotes. macOS and Linux can use single or double quotes.
> pipe "literal a man a plan a canal panama | reverse | console"
> Executed this way, the executed class image will not be written to disk. When the pipe is named, for example test1 with a (test1) prologue, this name will be used for the class image, instead of a generated unique name. Naming a pipe will enable specification of options for the compiler, like the pipe separator character.
> pipe "(test1 sep !) literal a man a plan a canal panama ! reverse ! console"
> As of pipes for NetRexx 3.08 the default separator is the | (pipe) symbol, as in zVM/CMS. The above example shows how to use the previous default, the exclamation mark.
> Options are:
> Option
> Function
> Remarks
> sep	defines stage separator	default |
> runaway	will monitor runtime	must be numeric
> stall	will monitor pipeline stalls	must be numeric
> end	set end of pipe indicator	
> cont	set continuation indicator	
> debug	provide debug information	must be numeric
> Options that persist files, like -gen and -keep, will not work in this mode.
> Stages are precompiled and will be picked up from the NetRexx jar file. (If you employ your own, custom defined stages, make sure these are compiled and their .class files are on the CLASSPATH.)
> From the command line, compiled to a .class file
> In this mode, which uses the pipc command (for pipe compiler), a .class file will be persisted to disk. This class can be run as many times as needed, without the overhead of compilation. This would be the right mode for pipes that take different arguments when re-run.
> The pipe name needs to be specified, and will be the class name. When the class name exists, it will be overwritten.
> pipc "(test1) literal a man a plan a canal panama | reverse | console"
> The file test1.class can be run with the command:
> java test1
> Be sure to leave out the .class suffix when invoking java.
> Additional options in this mode:
> Option
> Function
> Remarks
> gen	additionally save .nrx class to disk	default is -nogen
> keep	keep from the .nrx generated java source	default is -nokeep
> Compiled from an .njp file
> When compiled from a file, the pipe specification must not be quoted. Pipes can be specified in so-called Portret Mode, which is the standard for more complex pipelines as it is easier to read.
> An example is:
> pipe (appendtest)
>  
>    gen 100  |
>    append gen 50  |
>    rexx locate /0/ |
>    console
> 
> Compile from an .njp file with additional stage definitions in NetRexx
> An example is:
> length1.njp
> pipe (lengthp) < length.nrx | length1 | console
>  
> import org.netrexx.njpipes.pipes.
>  
> class length1 extends stage final
>  
>   method run()
>     do
>       loop forever
>     line = rexx peekto()
>     l = line.length
>     output(l l.d2x line)
>     readto()
>       end
>     catch StageError
>       rc = rc()
>     end
>     exit(rc*(rc<>12))
> In this example, the name of the generated pipe is lengthp, while the name of the custom stage is length1. Be sure to invoke the right class, invoking length1 will have the JVM complain about a non-existing main method.
> This class (lengthp) will be generated by the command:
> pipc length1
> note that the .njp suffix is optional when invoking the pipes compiler. When run, it tries to read the contents of the file length.nrx and will put out its lines, prepended by the line length in decimal and hex.
> 
> 
> 
> best regards,
> 
> René.