Loading with the SIRPUT utility
The SIRPUT utility can be used to load a mainframe file into a Model 204 procedure, solving some of the problems inherent with the types of files that may be stored as procedures for Janus Web Server.
An additional utility named SirPipe formerly performed the same basic function, but it is now obsolete and is no longer available for download. Nonetheless a full description of its use is provided below for those customers that have already installed the utility.
SIRPUT is a utility which allows you to load text or binary files to any Web server (like Janus Web Server) that supports HTTP PUT.
SIRPUT is written in C, and has been compiled for IBM VM and MVS systems. SIRPUT uses IBM TCP/IP socket calls, and requires IBM TCP/IP on the host computer, under OS/390, MVS, or VM operating systems. The IBM C/370 runtime library is also required.
Rocket provides the source code for SIRPUT in case custom modifications are necessary for your site.
SIRPUT is distributed in object form on the downloads page. Help to download and install the utility can be found at
SIRPUT EXEC or command processor syntax
SIRPUT filename [( [options] ]
|filename||A CMS or MVS filename.|
|options||One or more of the following:
Running SIRPUT under CMS
Use the SIRPUT EXEC under CMS to set up the environment for the SIRPUT module. For most installations, modifications will be unnecessary, but you may need to change the name of the C run-time library if you are not using the standard IBM name, IBMLIB.
Running SIRPUT under MVS
The SIRPUT load module resides in
SIRIUS.LOAD. A REXX command
procedure with the same name is in
SIRIUS.LIB. This command procedure
invokes SIRPUT from
SIRIUS.LOAD. If you use a different load library
at your site, you must update the SIRPUT REXX command procedure with this name.
SIRPUT requires access to the C runtime environment whether running in batch or in a TSO session.
Running SIRPUT in batch
The following job control can be used to invoke SIRPUT in batch. The
jobstep return code is set to zero if successful, or the HTTP return code
if it fails. This job control includes a steplib concatenation for
which contains the C runtime modules, but this library is commonly in the
OS/390 link list, therefore the statement is usually unnecessary.
//SIRPUT JOB (0),CLASS=A,MSGCLASS=A //SIRPUT EXEC PGM=SIRPUT,REGION=0M, // PARM='POKEMON.DITTO -t -r /ASH/DITTO.TXT' //STEPLIB DD DSN=SIRPUT.V100.LOAD,DISP=SHR // DD DSN=CEE.SCEERUN,DISP=SHR //SYSPRINT DD SYSOUT=* //
SIRPUT return codes
SIRPUT will terminate normally with a return code of 0, which means that SIRPUT created the object on the server. This is the equivalent of HTTP return code 201. All other return codes from 200-599 match the HTTP 1.0 specifications.
|4||Required argument is missing|
|8||Error connecting to Web server|
|12||Invalid file name or file not found|
|401||Not Authorized (logon required)|
|500||Internal Server Error|
JANWEB rules for SIRPUT
Before you can use SIRPUT with Janus Web Server, you must specify rules which define how PUT requests will be handled. You should restrict usage by IP address or by IP group, since SIRPUT cannot be used on an SSL port, and it does not accept authorization challenges.
The following example shows how one might tailor Janus Web Server rules for use with SIRPUT:
* * Any PUT requests will be loaded into file UPLOADS as * Model 204 procedures * JANUS WEB MYSERVER ON PUT /*.* OPEN FILE UPLOADS RECV *.* * * Only allow users at the following addresses to use SIRPUT * JANUS WEB DEFINEIPGROUP PUTTERS - 18.104.22.168-3 22.214.171.124 JANUS WEB MYSERVER ALLOW PUT *.* IPGROUP PUTTERS *
SIRPUT does not support the redirecting of requests: it will not forward a PUT request to another server, regardless of its location. A REDIRECT request will result in an error and a SIRPUT return code of 301 or 302.
SIRPUT will not accept authorization challenges.
This means that
you cannot create (PUT) a URL that requires a login userid and password.
Since SIRPUT does not support SSL, any userid and password would
traverse the network unencrypted, usually not a desirable situation.
IPGROUP on your JANUS WEB ALLOW rules to
restrict use of SIRPUT.
Overview of SIRPIPE
SIRPIPE is a program that copies an input stream to an output stream. It is typically used for preparation of input to the BATCH2 program, which provides an input stream to a Model 204 Online program. SIRPIPE consists of a single stand-alone load module.
SIRPIPE uses multi-buffered BSAM input for the input stream. This allows overlap of BSAM input and other processing. In addition, this allows SIRPIPE to take advantage of chained scheduling under MVS.
SIRPIPE has special provisions to provide an output stream that is well-suited for input to BATCH2, particularly when used for loading streams into Model 204 procedures. SIRPIPE also has special provisions for storing binary files, usually graphic images, for use with Janus Web Server.
SIRPIPE overcomes some limitations due to the Model 204 and/or MVS or CMS environments.
SIRPIPE will run under both MVS and CMS.
Running SIRPIPE consists of defining the input and output data sets and directing the operating system to invoke the SIRPIPE program. Invocation is shown below for each operating system; data set definition is shown below in an operating-system independent form. For examples of data set definitions specific to the operating system, see SIRPIPE example for MVS and SIRPIPE example for CMS.
Invoking PGM=SIRPIPE in MVS
This is the skeleton JCL used to invoke SIRPIPE in MVS:
//PIPESTEP EXEC PGM=SIRPIPE,PARM='CC=ccval' //STEPLIB DD DISP=SHR,DSN=... Rocket load library //SYSUDUMP DD SYSOUT=* //... DD ...
Invoking SIRPIPE module in CMS
This is a skeleton REXX program used to invoke SIRPIPE in CMS:
/* Invoke SIRPIPE */ 'FILEDEF ... 'M204CMS SIRPIPE (CC ccval'
Note that there is no equal sign between
ccval; the Model 204 CMS Interface (M204CMS)
inserts an equal sign between them before the SIRPIPE module
SIRPIPE program parameters
|CC=||This is the continuation column value, which defines the handling of long input records in the |
DD names/FILEDEF statements
All input and output data sets must be defined and available to
SIRPIPE via either the FILEDEF statement in the CMS environment
or the DD statement in the MVS environment.
In the description of SIRPIPE, the term
DD is used to refer to the both the DD statement under MVS and the FILEDEF statement under CMS.
DCB parameters are not required on any input nor output DD statements. SIRPIPE supports unlike data set concatenation for all input data sets. Following are the restrictions on DCB parameters for SIRPIPE data sets.
|PIPEIN||PIPEIN is the data set that is the primary input to SIRPIPE. Every record is either copied directly to PIPEOUT or interpreted as a SIRPIPE directive as explained in SIRPIPE transformations and directives. The restrictions on SIRPIPE's DCB parameters also apply to any data set opened as a result of an inclusion directive.
|PIPEOUT||PIPEOUT is the primary output from SIRPIPE, containing records exactly as they occurred in PIPEIN and transformed records from data sets processed as a result of SIRPIPE inclusion directives.
|PIPRINT||PIPRINT is the data set that receives SIRPIPE messages and warnings.
SIRPIPE transformations and directives
SIRPIPE transforms the input stream (DD SIRPIPE)
according to the mode
in effect at the beginning of each input record.
The mode can be changed by a special record in the input stream,
called a directive.
In all modes, if PIPEOUT is
RECFM F[B], trailing blanks are added to the
input record if it is shorter than the PIPEOUT
The purpose of this mode is to compensate for the fixed length
input processing of Model 204, as set by the Model 204
INCCC parameter, and to strip trailing blanks.
In this mode, trailing blanks are stripped from
each input record.
The record is then copied unchanged to the
output stream, unless the input record contains non-blank
characters at or past position
CC (if CC is greater than 0).
Records with non-blank characters at or past
this are split into pieces of length
CC-1 followed by a non-blank character.
The CC parameter must be less than or equal to the
LRECL (minus 4 for variable length output).
See Text (HTML) considerations for considerations when using SIRPIPE for creating text objects.
The purpose of this mode is to compensate for a number of Model 204 input constraints:
- Fixed-length input processing
- Special meaning of certain input lines, such as *LOWER, *ANCEL, and END PROCEDURE
- The loss of trailing blanks on some input lines
- The handling of procedure line end characters
- The possibility that errors in the beginning of the BATCH2 stream (for example, an incorrect file password) causes procedure input lines to be processed as Model 204 commands. This can result in large numbers of error messages at the audit trail, or possibly invoking commands unintentionally.
In addition, the record boundaries in the input stream are discarded; that is, all input records read in this mode are treated as a continuous stream of input bytes.
In this mode, the input stream is split into fixed-length
pieces, and each piece is prefixed by
* and suffixed by
Note that procedures stored with
BINARY in SIRPIPE may not be
written correctly by the output of the DISPLAY PROCEDURE
command (due to LINEND characters within the procedure).
If you use DISPLAY to dump your procedures,
BASE64 should be used with SIRPIPE.
The purpose of this mode is to compensate for the Model 204 input constraints described for Binary mode, and also to transform the procedure to entirely readable characters. This may be worthwhile in some environments to prevent a DISPLAY PROCEDURE command (which is really of little value on, for example, an image file) from causing 3270 terminal output errors, or to allow dumping a procedure with a USE OUTPUT command followed by DISPLAY PROCEDURE.
In this mode, the input stream is transformed, six bits at a time, into mixed-case
alphanumeric characters or slash (/) or plus (+)
and split into fixed-length pieces; each piece is prefixed by
* and suffixed by
Inclusion directive: #< ddname
One of the following records (starting in column 1) may occur in the input stream while in text mode:
#< ddname TEXT [cc] *< ddname BINARY [type] *< ddname BASE64 [type]
If such a record occurs, the current input data set is suspended, and the input data set referenced by the DD statement with name ddname is used for the input stream. (The uppercase translation of ddname is used; that is, you can specify either uppercase or lowercase.) At the end of this input data set, the suspended data set is resumed in text mode.
|TEXT||Indicates that the new data set is processed in text mode.|
|BINARY||Indicates that the new data set is processed in binary mode; input data bytes form a sequence with record boundaries ignored. The output is broken up into pieces.|
|BASE64||Indicates that the new data set is processed in Base64 mode; input data bytes form a sequence with record boundaries ignored. Each 6 bits of the input is translated into an alphanumeric character or slash (/) or plus (+). The output is broken up into pieces.
Note that the SIRPIPE Base64 mode does not add trailing equal sign (=) characters, which are sometimes used to pad the output to a multiple of 4 characters.
If the mode keyword is omitted, TEXT mode is used.
After the mode keyword the following options may be used:
|type||In the BINARY and BASE64 inclusion directives, type can be any character string (ended by a blank) that will be placed into an output header line for "Content-type". The maximum length of type is 51 characters; if longer, it will be truncated.
There is no default type; if missing, a header line for "Content-type" is not produced.
|cc||In the TEXT inclusion directive, cc can be an integer from 0 to the output LRECL. If it is 0, input lines must not be longer than the output LRECL. If it is between 1 and the output LRECL, input lines are broken into pieces of length cc-1 with a non-blank character added.
The default value of cc is 0.
Text (HTML) considerations
Using the Janus Web Server, a procedure can be sent as a BINARY, BASE64, or TEXT type object. The BINARY and BASE64 types use structuring within the procedure to recreate the data which was stored using SIRPIPE. BINARY and BASE64 types are also handled by SIRPIPE so that they can always be part of a BATCH2 procedure definition stream.
It is recommended that, whenever possible, you use BINARY or BASE64 types. Note that this is possible with HTML types, and in some cases it is necessary for HTML types. The only disadvantage is that you lose the Janus Web Server substitution facility for non-TEXT types.
The situations which are not valid for TEXT types being used for BATCH2 procedure definition streams are the following:
- Lines longer than 255 bytes; this is the limit for Model 204 procedures.
- Lines which begin with
*CANCEL(in either uppercase or lowercase, for some of these).
- Lines which contain only the words
END PROCEDURE, or which contain the words
END PROCEDUREfollowed by the name of the procedure being defined.
- Lines which contain the LINEND character.
TEXT type objects are stored as normal Model 204 procedures and when retrieved the procedure is separated into lines using the LINEND value of the procedure. The LINEND value of the procedure is set to the value of the LINEND user parameter when the procedure is created with the PROCEDURE command. (The COPY PROC command copies the LINEND value of the input procedure to the output procedure.)
The default Model 204 value of LINEND is semicolon (
X'5E'); this value is useful for typing a multi-line ad-hoc request (
However, there are many cases in using text types for Janus Web Server
in which it is useful to have a semicolon as part
of the text; for example, to insert a "less than" symbol in
HTML, the characters
'<' are used.
Therefore, when using SIRPIPE in TEXT mode it is recommended
that the value of LINEND be set to a value which is unlikely
to occur in the input.
Rocket has found the value
X'30' to be adequate; it happens
to be the smallest value which is not an EBCDIC graphic nor a control character.
The value of LINEND will not affect Janus Web Server operations with objects sent as BINARY or BASE64.
If you have a procedure and want to change its LINEND value, you can use the fact that the GET command of the Model 204 editor changes the LINEND value of the procedure being edited to become the LINEND value of the procedure referenced on the GET command. Here is an example to illustrate this:
R LINEND X'5E' PROCEDURE FOO Begin Print 'Been there, done that' End END PROCEDURE FOO R LINEND X'30' PROCEDURE BAR END PROCEDURE BAR EDIT FOO GET BAR (move the cursor to the comma and change to semicolon) END INCLUDE FOO
SIRPIPE example for MVS
The following job steps invoke SIRPIPE and BATCH2 to load an image file to a Janus Web Server Model 204 Online region:
//SIRPIPE EXEC PGM=SIRPIPE //STEPLIB DD DISP=SHR,DSN=SIRIUS.V404.LOAD //SYSUDUMP DD SYSOUT=* //PIPRINT DD SYSOUT=* //PIPEOUT DD DISP=(,PASS),UNIT=SYSDA, // SPACE=(TRK,(10,10),RLSE),DSN=&&PIPEOUT //IMFILE DD DISP=SHR,DSN=WEB.IMAGES.GIF(SMILE) //PIPEIN DD * LOGON WEBADMIN ADMPASSWD OPEN DEVWEB DEVWEB *LOWER R SUB 0 R INCCC 72 R LINEND X'30' DELETE PROCEDURE JANWEB/IMAGES/SMILE.GIF PROCEDURE JANWEB/IMAGES/SMILE.GIF #< IMFILE BINARY IMAGE/GIF END PROCEDURE JANWEB/IMAGES/SMILE.GIF //BATCH2 EXEC PGM=BATCH2,PARM='M204PROD' //STEPLIB DD DISP=SHR,DSN=M204.V3R1.LOAD //SYSUDUMP DD SYSOUT=* //CCAOUT DD SYSOUT=* //CCAIN DD DISP=OLD,DSN=&&PIPEOUT
Note that the
*LOWER command and the various
are inserted here by hand, similar to the way they are inserted
in the output file generated by the PIPEUP EXEC which is shown
in SIRPIPE example for CMS.
SIRPIPE example for CMS
The following CMS exec can be used in conjunction with a PIPEUP NAMES file which resides either on the same minidisk as PIPEUP EXEC or on the A disk:
/* BHELP Load image file for Janus Web Usage: XEDIT PIPEUP NAMES EXEC PIPEUP filenm filetp [*|filemd] [BINARY|BASE64|TEXT] [[PROC] procname] EHELP */ address command arg fn ft fm rest if arg(1) = '?' then call usage 0 parse source . . execname . execmode . address command 'STATE' execname 'NAMES A' if rc ^= 0 then 'STATE' execname 'NAMES' execmode if rc ^=0 then call usage rc, execname 'NAMES not on A nor', execmode 'disk' 'NAMEFIND :nick' execname ':online :file', ':filpswd :prefix :login :logpswd', ':lgctlcms :linend :dsn', '(STEM info. FILE' execname if rc ^= 0 then call usage rc, 'Unable to get info from', execname 'NAMES' online = info.1 procfile = info.2 filpswd = info.3 prefix = info.4 login = info.5 logpswd = info.6 lgctlcms = info.7 linend = info.8 dsn = info.9 'SET CMSTYPE HT' 'STATE' fn ft fm /* Did user give filemode? */ r = rc 'SET CMSTYPE RT' if r ^= 0 then do /* Is input file there? */ address command 'STATE' fn ft '*' if rc ^= 0 then call usage rc, 'Input file not found:', fn ft '*' rest = fm rest fm = '*' end proc = encode = 'BINARY' do while rest ^= parse var rest r rest t = translate(r) if find('BINARY BASE64 TEXT', t) > 0 then encode = t else if t = 'PROC' then parse var rest proc rest else do if proc ^= then call usage 1, 'Invalid arg:' r proc = r end end if proc = then proc = prefix || fn'.'ft 'ERASE PIPE IN A' p = 'EXECIO 1 DISKW PIPE IN A (STR' if login = '=' then login = p 'LOGON' login if lgctlcms = 'NP' then do if login = then logpswd = else if login = userid() then logpswd = end p logpswd if dsn ^= then p 'ALLOCATE' procfile 'WITH SCOPE=SYSTEM', 'DSN='dsn 'DIRECT OLD' p 'OPEN' procfile p filpswd p '*LOWER' p 'R SUB 0' p 'R INCCC 72' if linend ^= then p 'R LINEND' linend p 'DELETE PROCEDURE' proc /* Help avoid errors from proc-ending lines */ p 'RESET ERMX 0' p 'PROCEDURE' proc cont = 'IMAGE/'ft if ft = 'JPG' then cont = 'IMAGE/JPEG' if encode = 'TEXT' then cont = '72' p '#< IMFILE' encode cont p 'END PROCEDURE' 'FINIS * * *' call fd 'IMFILE DISK' fn ft '*' 'EXECIO 1 DISKW M204IFAM EXEC A 1', '(FINIS ST /**/push' online call fd 'PIPEIN DISK PIPE IN A' call fd 'PIPEOUT DISK PIPE OUT A' call fd 'PIPRINT DISK PIPE PRINT A' 'GLOBAL TXTLIB M204CMI' if rc ^= 0 then call usage rc, 'Error performing GLOBAL TXTLIB' 'M204CMS SIRPIPE (CC 72' if rc ^= 0 then call usage rc, 'Error performing SIRPIPE.' call fd 'CCAIN DISK PIPE OUT A' call fd 'CCAOUT DISK BATCH2 LISTING A' 'M204BAT2 LINE 34' exit rc /*--------*/ fd: procedure expose det parse arg dd rest 'FILEDEF' dd 'CLEAR' 'FILEDEF' dd rest if rc = 0 then return call usage rc, 'Error performing FILEDEF' dd rest /*--------*/ usage: parse arg r, m if m ^= then say m i=1 do while left(sourceline(i),7)^='/*BHELP' i=i+1 end i=i+1 do until left(sourceline(i),5)='EHELP' say sourceline(i) i=i+1 end exit r /*--------*/
The following file can be used to establish various parameters
for PIPEUP EXEC.
A system-wide copy can be kept on the same minidisk as PIPEUP EXEC,
while a user-tailored version can be kept on the A disk.
= as the value of the
indicates that the CMS user ID is known to Model 204, and the
LOGCTL NP CMS command is in effect.
The value of
X'30' for the LINEND parameter is useful in loading
a text file that contains semicolons; see Text (HTML) considerations.
* Control PIPEUP EXEC :nick.PIPEUP :online.M204WEB :prefix.JANWEB/IMAGES/ :file.WEB :filpswd.WEB :dsn.M204WEB.WEBPROC :login.= :lgctlcms.NP :logpswd. :linend.X'30'
The following messages are issued by SIRPIPE. Except where noted, SIRPIPE processing is terminated after any of these errors.
|PIPE0001 SIRPIPE version version||This displays the version of SIRPIPE that is running. With this version, version is |
SIRPIPE processing continues after this message. It does not indicate any error condition.
|PIPE0002 Unable to open DDname.||This indicates that SIRPIPE was unable to open the indicated DDname. This is probably due to a missing |
|PIPE0003 Invalid RECFM for DDname.||This indicates that the RECFM specified on the indicated DDname is not acceptable to SIRPIPE. If you do not need to control the RECFM, just omit it and let SIRPIPE calculate a default. See DD names/FILEDEF statements.|
|PIPE0004 Invalid LRECL for DDname.||This indicates that the LRECL specified on the indicated DDname is smaller than that acceptable to SIRPIPE. If you do not need to control the LRECL, just omit it and let SIRPIPE calculate a default. SIRPIPE requires certain mimimum LRECL values for both |
|PIPE0005 ddNAME has incompatible BLKSIZE (blksize) and LRECL (lrecl).||This indicates that the |
|PIPE0006 Getmain request failed, RC=code. SIRPIPE terminated||This indicates that there was not sufficient storage for some SIRPIPE operation. Increase the amount of storage allocated to the region with the REGION parameter on the EXEC card under MVS or with the DEFINE STORAGE command under CP.|
|PIPE0007 Cancelling run because of OUTPUT error in record recnum.||This indicates that an input record was too long (in |
|PIPE0008 Too many buffers for DDname.||This indicates that the product of BUFNO and BLKSIZE (increased by a small value) exceeds the largest 4-byte integer (about 2 billion). Change BUFNO to a more reasonable value (BLKSIZE is not the cause of this). This is checked for the PIPEOUT and PIPRINT outputs.|
|PIPE0009 End of SIRPIPE.||This indicates that SIRPIPE has completed processing. It does not indicate any error condition.|
|PIPE0011 Invalid DD name: string.||This indicates that the string that occurred on an inclusion directive ("<# statement") does not follow the MVS or CMS rules for DD names. Probably, the name is longer than 8 characters.|
|PIPE0012 Invalid mode keyword: string.||This indicates that the string that occurred on an inclusion directive (|
|PIPE0013 Terminated because of |
'SYSTEM | USER' abcode Abend; PSW psw MAIN address.
|This indicates that a severe error condition was detected. Call Rocket Software and report the problem.|
|PIPE0014 Initial parameter settings:||This indicates that the initial parameter values will be shown next on PIPRINT. Each parameter will be shown on a single line, with the parameter name, an equal sign (=), and the parameter value. Currently, the only SIRPIPE parameter is CC.
SIRPIPE processing continues after this message. It does not indicate any error condition.
|PIPE0015 Invalid parameter name: string.||This indicates that an invalid parameter name (string) was specified on the invocation of SIRPIPE (for example, the |
|PIPE0016 Invalid expression setting parameter param.||This indicates an error in the specification of a value specified for parameter param. on the invocation of SIRPIPE (for example, the |
where n is a positive integer.
|PIPE0017 Continuation Column value beyond PIPEOUT LRECL||This indicates that the value of the CC parameter is too large for the LRECL of the PIPEOUT data set. CC cannot exceed the LRECL if PIPEOUT is |
SIRPIPE return codes
SIRPIPE will terminate with one of the following return codes:
|0||SIRPIPE successfully completed.|
|4||SIRPIPE encountered a potentially non-fatal error.|
|8||SIRPIPE encountered a probably fatal error.|
|12||An invalid PARM card value was encountered.|
|40||SIRPIPE could not open the PIPRINT DD.|
|48||Insufficient storage to even initialize SIRPIPE.|
Installing SIRPIPE in MVS
SIRPIPE is distributed on a magnetic tape which also contains the all the other Rocket M204 products you purchased. Since SIRPIPE is only distributed with Janus Web Server, SIRPIPE will be on the tape that includes the Sirius Mods. Please refer to the Sirius Mods Installation Guide, which explains how to unload the tape.
After loading the tape, SIRPIPE is ready to use. The first tape file contains two sample jobs for SIRPIPE. One job called LINKPIPE is a sample link job. This job can be used to re-link the SIRPIPE load module should this become necessary. It should not be necessary since you unloaded from the tape a library with a fully linked SIRPIPE load module. There is also a sample SIRPIPE job called PIPEUP. This is only provided to be used as a skeleton for your own SIRPIPE jobs.
Installing SIRPIPE in CMS
SIRPIPE is distributed on a magnetic tape. This magnetic tape always contains all the Rocket M204 products you have purchased. Since SIRPIPE is only distributed with Janus Web Server, that tape will include the Sirius Mods Please refer to the Sirius Mods Installation Guide, which explains how to unload the tape.
The SIRPIPE files that will be loaded are:
- SIRPIPE MODULE
- SIRPIPE MAP
- SIRPIPE TEXT