Previous Topic
Table Of Contents
Parent Topic
Next Topic

The SWSFILE Function with Other REXX-language Interpreters

Related Topics

Web Server API Function Index

	May be used in Shadow/REXX
	May be used from Other REXX Interpreters
	High-level Language Interface available

When used with Other REXX-language Interpreters SWSFILE built-in function can be used to transmit data with an external dataset directly to a Web client. It may also be used to retrieve information about external datasets for the REXX-language procedure. 

SWSFILE Syntax

The SWSFILE function incorporates several operation types. The first argument to the function call must be the name of the specific operation to be performed. The remaining arguments needed for the function call depend on which operation is being invoked.

The general form for a REXX-language invocation of SWSFILE is:

   rc = SWSFILE( opertype, arg1, ... , argn )

Valid Operation Types

One of the following operation types must be coded as the first argument to the call (shown as opertype in the example above).

SEND

Transmit file-resident data to outbound to a Web client. This is a generic function which can operate upon PDS, PDSE, or QSAM datasets. .

STATS

Return statistical information about a PDS member or a sequential dataset.

The remaining arguments which must be coded for each operation type is given below. A table, at the end of this page, explains how to code each of the arguments.

Whenever text format data is transmitted to a Web client (SEND operations), the Server processes HTML Extension Statements to tailor the output. This facility allows the file-resident data to be customized at run-time.

New REXX-language applications should use the enhanced operation types (SEND, and STATS) since they support both PDS and sequential dataset organizations and allow dataset names to be specified using either a DD name or fully-qualified dataset name.

Top

The SEND Operation

SEND is used to transmit a member of a PDS dataset or a sequential dataset to the Web client. The function will create and transmit an HTML response header, followed by the file-resident data.

Coding SEND Requests

To code the SWSFILE function call for SEND, use the following format:

   zrc = SWSFILE("SEND",nametype,filename,mbrname,mimetype,datafmt,htxopt)

The arguments for the call are explained in the
SWSFILE Arguments Table below. 

Run-time Operation of SEND

SEND can operate on RECFM F, FB, V, VB, or U datasets. RECFM VB is suggested for binary data, and RECFM FB is suggested for text data.

When the PDS member or sequential dataset is transmitted outbound, any record-length fields (such as are present for VB format records) are removed and only the raw data is transmitted.

The input file data may be ASCII binary data or EBCDIC text data.

If "TEXT" format data is specified, trailing EBCDIC blanks are removed from each data record before an ending CR (carriage return) character is appended. Each line is translated from EBCDIC to ASCII before transmission.

Unless "NOHTX" was explicitly specified on the function request, HTML Extension values are processed before the member is transmitted. When HTML Extensions are actually present within the input member, transmission of the Last-Modified: HTTP response header is suppressed. Instead, an Expires: header is generating giving the current time.

If ISPF-type statistics exist for the PDS member the ISPF last-modified data is used to generate the Last-Modified: HTML response header; otherwise, the Last-modified: HTML response header is not generated. The Last-modified: response header is surpressed if HTML Extension Statements are present and might cause the data to be tailored different for a future request.

SEND checks the HTTP transaction headers before actually transmitting the full PDS member outbound. If the inbound HTTP transaction method is "HEAD", only the HTML response header information is transmitted. Similarly, if the inbound URL contained an If-modified-since: specification the Server may transmitted a "Not Modified" (304) response instead of sending the contents of the file.

The outbound transmission generated by a successful SEND operation constitutes an entire and complete HTTP response. The REXX process which issues the SWSFILE function should not transmit additional data to the Web client unless some error is returned by the function.

SEND Return Values

Top

The STATS Operation

STATS is used to check the status of a PDS member or sequential dataset and return to the REXX procedure information about that member or sequential dataset. This information can be useful in dynamically creating transaction responses from within the REXX procedure.

Coding STATS Requests

   zrc = SWSFILE("STATS",nametype,filename,mbrname,datafmt)

The arguments for the STATS operation are described in the SWSFILE Arguments Table below.

Run-Time Operation of STATS

STATS can operate of RECFM F,FB, V, VB, or U datasets.

STATS returns a content length, record count and last modification date value which corresponds to information which would be required to transmit the member outbound to a Web client.

STATS Return Values

For binary format data the member size or sequential dataset size returned will reflect an exact count of the data bytes within each logical record of the PDS member or sequential file.

For text format data the member or sequential file is treated as EBCDIC text. In calculating the member or sequential file size, trailing EBCDIC blanks are eliminated, and 1 additional byte per logical record (for the trailing carriage return character) is assumed. If a zero-length record is encountered within a RECFM=V or RECFM=VB file, a single blank is substituted for the zero-length record (zero-length records cannot be created in text files using ISPF, however, then may be present if the data has been uploaded to MVS via FTP).

STATS returns a NULL string if the dataset does not exist, or member does not exist within the specified PDS, or if the dataset cannot be accessed.

The STATS function returns a character string suitable for processing by REXX using blank-delimited word type processing.

The returned string contains the following information:

Word 1

Set to the value YES or NO to indicate whether or not ISPF statistics were present within the PDS directory for the member.

Word 2

Contains the integer value representing the length, in bytes, of the member or sequential dataset.

Word 3

Contains the count of logical records within the member or sequential dataset.

Word 4&ff

The remainder of the string contains the HTTP formatted Last-Modified: data and time stamp and is derived from the ISPF last-update time. This information is omitted if ISPF statistics are not present for the member.

 

SWSFILE Arguments Table

The table which follows describes each of the arguments which can be supplied for an SWSFILE function call.

Argument Name given in Syntax Examples	Description of Argument
nametype	Indicates whether the filename argument on the function call is an MVS DD name or a fully-qualified dataset name. The nametype argument must be one of the following: DDNAME or DD Indicates that the filename argument is a DD name value. The DD name must be allocated to the Shadow OS/390 Web Server address space. DSNAME or DSN Indicates that the filename argument is a fully-qualified MVS dataset name.
filename	Specifies the dataset to be operated upon by the function call. The dataset specification can be made using either an MVS DD name value or as a fully-qualified dataset name. must be a PDS, PDSE, or sequential dataset. DD name values must be given as an 8-byte, blank-padded string. Fully-qualified dataset names must be given as a 44-byte, blank-padded string. When a DD name is used, it must be pre-allocated to the Server address space. You specify whether a DD name or dataset name is being passed on the call using the nametype argument shown above. For the legacy operations (PDSSEND, PDSSTATS, and PDSQUEUE) only an 8-byte DD name is permitted. The DD name must reference a PDS or PDSE dataset.
mbrname	The 8-byte, blank padded member name to be transmitted from a PDS or PDSE dataset. This argument must be specified when the SWSFILE operation refers to a PDS or PDSE dataset. It should be omitted when a sequential dataset is referred to (code a single comma in place of the argument).
mimetype	The 50-byte, blank padded MIME content type value to be used when the data is transmitted. The value coded here is used to generate the Content-type: outbound HTML response header. It may be set to any value, but would normally be set to 'image/gif', 'Text/HTML' or some other widely known value. The server does not perform a validity test upon this argument. If this argument is omitted, the Server assumes a default value of 'text/plain'.
datafmt	The format of the data contained within the file to be transmitted. Valid values are: TEXT Indicates that the data to be sent exists in text format. It is translated by the server, during output, to ASCII, trailing blanks are stripped, and a carriage return character is appended to each line. HTML Extension Statements, if any, within the data are processed by the Server. BINARY Indicates that the data to be sent exists in binary format. It is transmitted by the server, as is. If this argument is omitted, the Server uses BINARY as the default value.
htxopt	Indicate how (or if) HTML Extension Statements within the file data are processed by the Server before output. This argument should be omitted for binary format files, and is optional when text format data is processed. Valid values are: HTX Indicates that HTML extension processing should be performed during the output operation. NOHTX Indicates that HTML extension processing should not be performed during the output operation. HTXREXXRULES Indicates that uninitialized variables located during HTML extension processing are replaced with the upper-case variable name. Normal extension processing replaces uninitialized variables with a NULL string. If this argument is omitted, the Server assumes a value of HTX for all text format files.

 

Top