)F REXX function - Allocate, get/put, free in one go

Version: 005

Fixed in this build
 Fix mask problem with 1 char after last asterix i.a. ABC*F


Preface

 Tired of doing ALLOCATE and FREE just because you want to EXECIO
 against a dataset and you do not have the PIPE command installed,
 then this small program might be for you. It is actually slightly
 better than PIPE, as it pads and strips records automatically.
  It allocates the dataset and either reads from it or write to
 it, using a stem or the stack as source or target and freeing the
 datasets at the end.
  Dataset can be a sequential dataset, a pds member or a USS file,
 as long as it acceptable for the QSAM access method. Both fixed
 and variable record formats are accepted. The COPY command will
 accept any type as either input and output.


Syntax

  RXEXECIO is a REXX function, so must be used thus:

  rc=RXEXECIO(request)

  Requests

   Copy dataset or file to stem, stack, console or return-code.
    GET      DSN(name) | PATH(name) | IN(parm)
             STEM(stem.) | STACK | CONsole | RETVAL
             STArt(num) COUNT(num) END(num)
             INClude(mask) EXCLude(mask) MC(ao)
             UNNum ASIS

   Write stem, stack or value to dataset or file.
    PUT      DSN(name) | PATH(name) | OUT(parm)
             OUTDISP PATHMODE(mode)
             STEM(stem.) | STACK | TEXT(text)
             STArt(num) COUNT(num) END(num)
             INClude(mask) EXCLude(mask) MC(ao)

   Copy one dataset or file to another.
    COPY     DSN(name) | PATH(name) | IN(in)
             OUTDSN(name) | OUTPATH(name) | OUT(out)
             OUTDISP(disp) PATHMODE(mode)
             STArt(num) COUNT(num) END(num)
             INClude(mask) EXCLude(mask) MC(ao)
             UNNUM

   Return records from dataset or file as one string.
    COMBINE  DSN(name) | PATH(name) | IN(parm)
             STArt(num) COUNT(num) END(num)
             INClude(mask) EXCLude(mask) MC(ao)
             UNNUM

   Return version and assembly info.
    VERSION

  Parameter description

   DSn(name)       Datasetname for GET or PUT. Fully qualified, may
                   be quoted.
   OUTDSn(name)    Output datasetname for COPY. Fully qualified, may
                   be quoted.
   OUTDIsp(disp)   Output dataset disp. Default is SHR, also for PUT
                   and COPY output.
   PATH(name)      USS filename. Will be quoted internally to preserve
                   case.
   OUTPath(name)   COPY output USS filename. Will be quoted internally
                   to preserve case.
   PATHMode(mode)  USS pathmode for output file. Default is SIRWXU.
                   See 'Installation notes' later.
   IN(parm)        Full BPXWDYN parameter string for alloction the
                   input dataset or USS path excl of the ALLOC and
                   DDNAME parameters. Note that a USS path must be
                   quoted to preserve case.
   OUT(parm)       Full BPXWDYN parameter string for alloction the
                   output dataset or USS path excl of the ALLOC and
                   DDNAME parameters. Note that a USS path must be
                   quoted to preserve case.
   STEM(name)      Stem name, must include trailing dot (.).
                   Mutually exclusive with STACK and CONSOLE.
   STACK           Read into, or write from REXX stack.
                   Mutually exclusive with STEM and CONSOLE.
   TEXT(text)      Write text to dataset.
                   Mutually exclusive with STEM and STACK.
   CONSole         Display at the terminal (GET only).
                   Mutually exclusive with STEM, STACK and RETVAL.
   RETVal          Return 1st record as return value (RC).
                   Mutually exclusive with STEM, STACK and CONSOLE.
   STArt(num)      Start reading or writing by record num. Default
                   is 1.
   COUnt(num)      Stop reading or writing after num records after
                   start num.
   END(num)        Stop reading or writing at records num.
                   Note that this may leave records in the stack.
   INClude(mask)   Get or put record if mask matches record.
   EXClude(mask)   Get or put record if mask do not match record.
   MC(ao)          Mask characters for all-or-none and one.
                   Default is '*%'. Two characters must be specified.
   UNNUM           Drop sequence numbers for fixed-length datasets.
   ASIS            Keep record length - FB dataset only. Default is
                   to strip trailing blanks.

   Notes  Include, exclude, start and count/end may be used together.
          The start/count/end test is done first, then include and
          lastly exclude.

Return codes

   0  ok
   1  allocation error
   2  write truncation, variable RXEXECIO_TRUNC contains the number
      of the first truncated record.
   8  parameter error
  20  program abend
  version info if reuest is VERSION.
  contents of dataset / file if request is COMBINE.


Variables set

  RXEXECIO_REASON   Text with the reason for the bad return
  RXEXECIO_READN    Number of records read from dataset.
  RXEXECIO_WRITEN   Number of records written to dataset.
  RXEXECIO_PASSN    Number of records passed filter and startnum,
                    count and endnum processing.
  RXEXECIO_TRUNCN   Number of first truncated record when rc=2.


Samples

  rc=RxExecio('put dsn(a.seq.ds) stack')
  rc=RxExecio('put dsn(a.seq.ds) stem(data.)')
  rc=RxExecio('put dsn(a.pds(member)) stack')
  rc=RxExecio('get dsn(a.seq.ds) stem(list.) start(3) count(4)')
  rc=RxExecio('get dsn(a.seq.ds) stem(data.) incl(*Doctor*)')
  rc=RxExecio('copy dsn(a.seq.ds) outdsn(a.pds(member))')
  rc=RxExecio('get path(/tmp/my.test.text) cons')
  rc=RxExecio('put path(/tmp/my.test.text) stack')


Installation notes

 Fully reentrant, so can (should) be in the lpalib. If not, then
 the program will reload itself the first time, thus stay in the
 JPAQ. This can be disabled by setting the &JPAQ variable to 'N'.

 Default pathmode for USS file write is 'SIRWXU'. You can change
 that to i.e. 'SIRWXU,SIRGRP,SIROTH' by altering the assembler setc
 of &pthmode before assembly.