Previous Topic
Table Of Contents
Parent Topic
Next Topic

The SWSFILE Function

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

The REXX-language 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.
MBRLIST: Queue a list of PDS members to the REXX external data queue.
QUEUE: Read a PDS member or sequential dataset into the REXX external data queue. A return code value of 28 is returned if the external data queue is not sufficiently large to contain the entire file, or PDS(E) member. (Note: You can increase the size of the external data queue using the QUEUESIZE( ) keyword).
PDSSEND: Send a PDS member outbound to the Web client.
PDSSTATS: Return statistical information about a PDS member.
PDSQUEUE: Read a PDS member into the REXX external data queue.

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 (for the SEND or PDSSEND operations) or is placed into the REXX external data queue (for the QUEUE or PDSQUEUE operations), the Server processes HTML Extension Statements to tailor the output. This facility allows the file-resident data to be customized at run-time.

Note that the PDS-based operations (PDSSEND, PDSSTATS, and PDSQUEUE are legacy operations from an earlier release of the Server. They support only operations upon PDS datasets using a DD name specification. These legacy operations continue to be supported, however future enhancements will not be made to these operation types.

New REXX-language applications should use the enhanced operation types (SEND, STATS, and QUEUE) 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

Return Code	Definition of Code
0	The function was completed successfully. The outbound data stream was flushed from Web Server buffers.
4	The communciations link failed during outbound transmission.
8	The specified member name does not exist within the PDS.
12	Either the specified DDNAME (the filename operand) is not allocated to the Shadow OS/390 Web Server address space or the specified DSNAME does not exist.
16 or 20	There is an internal processing error, or abend condition.
24	The SECURITY(USERID) is in effect for the dataset and the effective userid does not have authority to the dataset.
28	The file exceeds the FILESATAGINGSIZELIMIT value set for pre-staging of data files. Normally such requests are re-driven automatically without pre-staging, but DDNAME format requests made from REXX procedures cannot be re-driven automatically and are rejected with this return code.
32	An HTML Extension processing error has occurred. This means the requested file or member has ot been sent. Instead, text or an HTML page containg a formatted description of the error was generated and sent to the client. However, the return code 16 is used whenever an HTML extension error occurs and an error description page cannot be generated.
36	The requested file has been migrated to offline storage, and is currently unavailable for processing. If DFHSM support was enabled within the Server, a recall of the dataset was requested; however, if the recall could not be completed within the time allowed, the dataset could still become available. If DFHSM support was enabled, no recall request was issued. A manual request for recall must be issued before the dataset is available.

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.

Top

The MBRLIST Operation

MBRLIST is used to obtain a list of the PDS members within a library. The list of member names is returned in the REXX external data queue. MBRLIST only operates on PDS or PDSE dataset types.

Coding MBRLIST

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


   zrc = SWSFILE("MBRLIST",nametype,filename)

The SWSFILE arguments for the MBRLIST operation are described in the SWSFILE Argument Table below.

Run-Time Operation of MBRLIST

MBRLIST only operations upon PDS or PDSE datasets. The MBRLIST function queues the list of PDS(E) members to the REXX external data queue. The list can be retrieved using the PARSE PULL REXX operation.

MBRLIST Return Values

Return Code	Definition
0	The function was completed successfully. The member list is queued.
12	Either the specified DDNAME (the filename operand) is not allocated to the Shadow OS/390 Web Server address space or the specified DSNAME does not exist.
16 or 20	There is an internal processing error, or abend condition.
24	The SECURITY(USERID) is in effect for the dataset and the effective userid does not have authority to the dataset.
28	The external data queue is not sufficiently large to contain the entire member list. (Note: You can increase the size of the external data queue using the QUEUESIZE( ) keyword).

If no members exist within the PDS, the function returns with an empty external data queue and sets return code 0.

The QUEUE Operation

QUEUE is used to read a member of a PDS dataset or a sequential file into the REXX external data queue. The QUEUE function is far more efficient than using EXECIO for a similar purpose, and allows you to reference a single DD name for all members of a PDS dataset.

The input source may be ASCII binary data or EBCDIC text data. If the input source is in text format, HTML Extensions within the source are processed before the source data is placed into the external queue.

Coding QUEUE

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


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

The SWSFILE arguments for the QUEUE operation are described in the SWSFILE Argument Table below.

Run-Time Operation of QUEUE

When the PDS member or sequential dataset is read and copied to the external data queue any record-length fields (such as are present for VB format records) are removed and only the raw data is copied. Trailing blanks are eliminated for TEXT format records. Additionally, for TEXT format records, if a zero-length VB record is read, a single blank is used for the corresponding queue entry (zero-length VB records can, and frequently are, created when members are shipped to an MVS system using FTP).

For binary format data no editing of any kind is applied to the data before it is copied to the external data queue. The data is copied to the queue as a continuous string of bytes with each queue entry being exactly as long as the corresponding source logical record.

For text format data each input record is stripped of trailing blanks before being copied to the external data queue.

NOTE: The maximum logical record length which can be stored in a REXX external data queue entry is 652 bytes. Logical records longer than 623 bytes will be truncated.

After checking the return code from the QUEUE operation, you can retrieve the records from the external data queue with REXX coding, such as:


   DO WHILE QUEUED() > 0
      PARSE PULL nextlogicalrecord
   END

QUEUE Return Values

Return Code	Definition
0	The function was completed successfully. The data was copied to the external data queue.
8	The specified member name does not exist within the PDS.
12	Either the specified DDNAME (the filename operand) is not allocated to the Shadow OS/390 Web Server address space or the specified DSNAME does not exist.
16 or 20	There is an internal processing error, or abend condition. The most likely cause of such an error is that the REXX external data queue has become full. The size of the REXX external data queue is fixed, but can be altered for Web Transaction programs by changing the SEFMAXQUEUE start-up parameter value.
24	The SECURITY(USERID) is in effect for the dataset and the effective userid does not have authority to the dataset.
28	The external data queue is not sufficiently large to contain the entire file, or PDS(E) member. (Note: You can increase the size of the external data queue using the QUEUESIZE( ) keyword).

Top

The PDSSEND Operation

PDSSEND is a legacy operation type from an earlier release of the Server. Equivalent operations may be requested using the SEND request, which is the preferred method for new applications.

Coding PDSSEND Requests

To code SWSFILE function calls using PDSSEND, use the following format:


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

Note that this operation type must supply a DD name as the filename argument. Use of a fully-qualified dataset name is not supported for this interface.

Also, note that the MVS dataset referred to must be either a PDS or PDSE dataset. Access to sequential datasets is not supported.

Run-Time Operation of PDSSEND

The operation of PDSSEND is the same as for the SEND request, shown above.

PDSSEND Return Values

Return values set by PDSSEND are the same as for the SEND request, shown above.

The PDSSTAT Operation

PDSSTAT is a legacy operation type from an earlier release of the Server. Equivalent operations may be requested using the STATS request, which is the preferred method for new applications.

Coding PDSSTAT Requests

To code SWSFILE function calls using PDSSTAT, use the following format:


   zrc = SWSFILE("PDSSTAT",filename,mbrname,datafmt)

Note that this operation type must supply a DD name as the filename argument. Use of a fully-qualified dataset name is not supported for this interface.

Also, note that the MVS dataset referred to must be either a PDS or PDSE dataset. Access to sequential datasets is not supported.

Run-Time Operation of PDSSTAT

The operation of PDSSTAT is the same as for the STATS request, shown above.

PDSSTAT Return Values

Return values set by PDSSTAT are the same as for the STATS request, shown above.

The PDSQUEUE Operation

PDSQUEUE is a legacy operation type from an earlier release of the Server. Equivalent operations may be requested using the QUEUES request, which is the preferred method for new applications.

Coding PDSQUEUE Requests

To code SWSFILE function calls using PDSQUEUE, use the following format:


   zrc = SWSFILE("PDSQUEUE",filename,mbrname,datafmt,htxopt)

Note that this operation type must supply a DD name as the filename argument. Use of a fully-qualified dataset name is not supported for this interface.

Also, note that the MVS dataset referred to must be either a PDS or PDSE dataset. Access to sequential datasets is not supported.

Run-Time Operation of PDSQUEUE

The operation of PDSQUEUE is the same as for the QUEUE request, shown above.

PDSQUEUE Return Values

Return values set by PDSQUEUE are the same as for the QUEUE request, shown above.

Top

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