John P. Hartmann
IBM Danmark A/S
18 Sep 2002 16:03:03
Printed in Denmark
First Edition (July 2002)
This document describes an interface to the co-pipes facility introduced in CMS/TSO Pipelines 1.1.9.
© Copyright International Business Machines Corporation 2002. All rights reserved.
Note to U.S. Government Users -- Documentation related to restricted rights -- Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule contract with IBM Corp.
The FPLPOP TEXT object module contains an interface to CMS/TSO Pipelines co-pipes that works on both MVS and CMS. Three sample programs are supplied to demonstrate the use with Assembler (POPEN ASSEMBLE), a C-language (CPOPEN C), and PL/I (PPOPEN PLIOPT).
Using the subroutines in FPLPOP you can create a pipeline to process output data from your program or you can create a pipeline that will supply data to your program, just like with the UNIX popen() function, which is mimicked by the four entry points provided in FPLPOP.
More complex uses that both supply and retrieve data from the pipeline must be programmed using the underlying co-pipe interface as described in CMS/TSO Pipelines: PIPE Command Programming Interface. Refer to http://vm.marist.edu/~pipeline.
FPLPOP supports Assembler, C, PL/I, FORTRAN, and COBOL, but only the first three have been tested.
The C-language interface is defined in FPLPOP H.
The user must provide a 256-byte work area on a doubleword boundary (32 doublewords) to give the subroutines in FPLPOP an anchor and a work area. The address of this work area is supplied as the first argument to all functions. In the C-language, the typedef fplpopwa may be used to define this work area; the first member should be initialised to zero.
In the following, the functions are described by their C-language names. For Assembler, the name must be truncated to eight characters and uppercased. For PL/I, a seven-character truncation is available.
Parameters are passed using the PL/I asm option, that is, parameters are by reference. This means that the parameter list has a pointer to an integer value.
The last parameter must be marked with the highorder bit of its address being one; that is, VL in Assembler parlance.
A program using the popen package will issue a fplpopen call to define the pipeline; then a number of fplpread or fplpwrite calls; and finally fplpclose to wind things down.
Note: Failure to call fplpclose will lead to resource leakage.
The functions set a return code in both general register 0 and general register 15.
In PL/I you may use the retcode option to have this
return code saved in the PLIRETV variable, or you can specify an
extra integer at the end of the parameter lists defined below;
or you can do both.
| 0 | The function completed successfully. |
| 4 | End-of-file on read. No record is made available. |
| 8 | Error starting the pipeline or some unknown error. |
| 12 | The read or write request was rejected by CMS/TSO Pipelines. |
| 16 | An incorrect number of arguments is specified. |
| 20 | The work area is not initialised. That is, fplpopen was not called or the work area supplied is not the one initialised. |
| 24 | The fitting name specified in a fitting stage is not FPLPOPEN. |
The open function defines the pipeline and starts it so that it is ready to process data.
Remember to supply a fitting stage to represent your program's place in the pipeline. The fitting name is FPLPOPEN. Fitting names are case sensitive; it must be specified in uppercase.
Dismantle the pipeline.
Supply a record to the pipeline.
/* Test of FPLPOP subroutines. */
/* John Hartmann 31 Jul 2002 19:49:00 */
static char IBM_Copyright¢¦=
"(c) Copyright IBM Corp 2002 All rights reserved.";
/*********************************************************************/
/* (c) Copyright IBM Corp, 2002. All rights reserved. */
/* */
/* An unmodified copy of this program may be freely distributed. */
/* */
/* Change activity: */
/*31 Jul 2002 New Module. */
/*********************************************************************/
#include "fplpop.h"
#include <string.h>
#include <stdio.h>
int
main(int argc, char ** argv)
{
fplpopwa wa={0};
enum fplpopflag flag;
char * wpipe="fitting FPLPOPEN|cons";
char * rpipe="literal OK?|literal Howdy C!|fitting FPLPOPEN";
char * data="Hello, Pipe!";
int dlen; /* When reading */
int rv;
flag=fplpop_write;
dlen=strlen(wpipe);
rv=fplpopen(&wa, &flag, wpipe, &dlen);
if (rv)
{
printf("Return value %d on open for write.\n", rv);
return rv;
}
dlen=strlen(data);
rv=fplpwrite(&wa, data, &dlen);
if (rv) printf("Return value %d on write.\n", rv);
fplpclose(&wa);
flag=fplpop_read;
dlen=strlen(rpipe);
rv=fplpopen(&wa, &flag, rpipe, &dlen);
if (rv)
{
printf("Return value %d on open for read.\n", rv);
return rv;
}
do
{
rv=fplpread(&wa, &data, &dlen);
if (rv)
{
printf("Return value %d on read.", rv);
if (4==rv) printf(" That means EOF.\n");
else printf(" That is an error. Tell John.\n");
}
else printf("Read: %.*s\n", dlen, data);
} while (0==rv);
return fplpclose(&wa);
}
/* popen sample. */ PPO00010
/* John P. Hartmann 16 Aug 2002 10:25:47 */ PPO00020
PPO00030
/********************************************************************/ PPO00040
/* (c) Copyright IBM Corp, 2002. All rights reserved. */ PPO00050
/* */ PPO00060
/* An unmodified copy of this program may be freely distributed. */ PPO00070
/********************************************************************/ PPO00080
PPO00090
P: proc options(main); PPO00100
dcl PPO00110
FPLPOPE entry external options(asm retcode), PPO00120
FPLPCLO entry external options(asm retcode), PPO00130
FPLPREA entry external options(asm retcode), PPO00140
FPLPWRI entry external options(asm retcode), PPO00150
PLIRETV builtin; PPO00160
PPO00170
dcl PPO00180
wa (32) binary float (53) init(0), PPO00190
wpipe char (32) init('fitting FPLPOPEN|cons'), PPO00200
rpipe char (64) PPO00210
init('literal OK?|literal Howdy PL/I!|fitting FPLPOPEN'), PPO00220
data char (16) init('Hello, Pipe!'), PPO00230
pdata pointer, PPO00240
dlen fixed bin (31), PPO00250
resp char (256) based(pdata); PPO00260
PPO00270
dcl /* Default numbers are packed decimal */ PPO00280
wflag fixed bin (31) init(1), PPO00290
rflag fixed bin (31) init(0), PPO00300
wplen fixed bin (31) init(23), PPO00310
rplen fixed bin (31) init(50), PPO00320
dalen fixed bin (31) init(12); PPO00330
PPO00340
call fplpope(wa, wflag, wpipe, wplen); PPO00350
if pliretv^=0 then stop; PPO00360
call fplpwri(wa, data, dalen); PPO00370
call fplpclo(wa); PPO00380
PPO00390
call fplpope(wa, rflag, rpipe, rplen); PPO00400
if pliretv^=0 then stop; PPO00410
PPO00420
call fplprea(wa, pdata, dlen); PPO00430
do while (pliretv=0); PPO00440
display (substr(resp, 1, dlen)); PPO00450
call fplprea(wa, pdata, dlen); PPO00460
end; PPO00470
call fplpclo(wa); PPO00480
PPO00490
end P; PPO00500
POPEN TITLE ' Sample program for FPLPOP. *00010000
Copyright 2002 IBM Danmark A/S' 00020000
SPACE 2 00030000
*********************************************************************** 00040000
* * 00050000
* (C) Copyright IBM Danmark A/S 2002 all rights reserved. * 00060000
* * 00070000
* An unmodified version of this file may be freely * 00080000
* distributed. * 00090000
* * 00100000
* This module shows how to call the subroutines in FPLPOP. * 00110000
* * 00120000
* When run as a CMS command, specify READ to test the reading * 00130000
* variety where the pipeline supplies data to the program; * 00140000
* specify WRITE to send data into the pipeline. * 00150000
* * 00160000
* Not re-entrant. * 00170000
* * 00180000
* Change activity: * 00190000
* 30 Jul 2002 New module by John P. Hartmann, CPHART(JOHN) * 00200000
* * 00210000
*********************************************************************** 00220000
SPACE 2 00230000
POPEN START 0 00240000
POPEN AMODE 31 00250000
POPEN RMODE ANY 00260000
USING POPEN,12 00270000
STM 14,12,12(13) 00280000
LA 14,SAREA 00290000
ST 13,4(,14) Defeat rent check 00300000
LR 13,14 00310000
CLC =CL8'READ',8(1) Which kind 00320000
BE READ 00330000
CLC =CL8'WRITE',8(1) ... 00340000
BE WRITE 00350000
LINEWRT DATA=DORW 00360000
LA 15,12 00370000
B EXIT 00380000
DORW DC C'Specify READ or WRITE.' 00390000
SPACE 1 00400000
CLOSE DS 0H 00410000
LR 5,15 00420000
LA 1,PCLOSE 00430000
L 15,=V(FPLPCLOS) 00440000
BALR 14,15 00450000
LR 15,5 00460000
EXIT DS 0H 00470000
L 13,SAREA+4 00480000
L 14,12(,13) 00490000
LM 0,12,20(13) 00500000
BR 14 00510000
SPACE 1 00520000
PCLOSE DC A(WORK+X'80000000') 00530000
SPACE 1 00540000
READ DS 0H 00550000
LA 1,ROPEN 00560000
L 15,=V(FPLPOPEN) 00570000
BALR 14,15 00580000
LTR 15,15 00590000
BNZ EXIT 00600000
LA 1,RREAD 00610000
L 15,=V(FPLPREAD) 00620000
BALR 14,15 00630000
LTR 15,15 00640000
BNZ CLOSE 00650000
LM 4,5,RDATA 00660000
LINEWRT DATA=((4),(5)) 00670000
LA 1,RREAD 00680000
L 15,=V(FPLPREAD) 00690000
BALR 14,15 00700000
LTR 15,15 00710000
BNZ CLOSE 00720000
LM 4,5,RDATA 00730000
LINEWRT DATA=((4),(5)) 00740000
B CLOSE 00750000
SPACE 1 00760000
ROPEN DC A(WORK,RFLAG,RPIPE,LRPIPE+X'80000000') 00770000
RPIP DC C'literal It really is.|' 00780000
DC C'literal The answer is 42!|fitting FPLPOPEN' 00790000
RPIPE EQU RPIP,*-RPIP 00800000
RFLAG DC F'0' 00810000
LRPIPE DC A(L'RPIPE) 00820000
RREAD DC A(WORK,RDATA,RDATA+4+X'80000000') 00830000
RDATA DS 2F 00840000
SPACE 1 00850000
WRITE DS 0H 00860000
LA 1,WOPEN 00870000
L 15,=V(FPLPOPEN) 00880000
BALR 14,15 00890000
LTR 15,15 00900000
BNZ EXIT 00910000
LA 1,WWRITE 00920000
L 15,=V(FPLPWRIT) 00930000
BALR 14,15 00940000
LTR 15,15 00950000
BNZ CLOSE 00960000
LA 1,WWRITE1 00970000
L 15,=V(FPLPWRIT) 00980000
BALR 14,15 00990000
B CLOSE 01000000
SPACE 1 01010000
WOPEN DC A(WORK,WFLAG,WPIPE,LWPIPE+X'80000000') 01020000
WFLAG DC F'1' 01030000
WPIPE DC C'fitting FPLPOPEN|console' 01040000
LWPIPE DC A(L'WPIPE) 01050000
SPACE 1 01060000
WWRITE DC A(WORK,WDATA,LWDATA+X'80000000') 01070000
WDATA DC C'Killroy Was Here!' 01080000
LWDATA DC A(L'WDATA) 01090000
SPACE 1 01100000
WWRITE1 DC A(WORK,WDATA1,LWDATA1+X'80000000') 01110000
WDATA1 DC C'He really was.' 01120000
LWDATA1 DC A(L'WDATA1) 01130000
SPACE 1 01140000
SAREA DS 9D 01150000
WORK DS XL256 01160000
END , 01170000