High-Level Language SWSFILE (SWCPFI) Function
Related Topics
 |
May be used in Shadow/REXX |
| |
May be used from Other REXX Interpreters |
| |
HLL entry point name is SWCPFI |
SWSFILE is the Web Server API function used to retrieve data from an MVS dataset and transmit it to a Web Client program. The caller specifies the MVS dataset from which data is to be retrieved and the MIME content type to be used when the information is transmitted.
For text format data, the Server processes HTML Extension Statements, if any, within the data file before the information is transmitted to the Web Client. This facility allows the information to be specially tailored in response to run-time conditions.
The SWSFILE (SWCPFI) interface supports two operation request types:
| SWS_FILE_SEND | This request type is used to invoke outbound transmission of a PDS dataset member
(BPAM or PDSE), or a sequential dataset (QSAM). This request type contains all of the
functionality formerly incorporated into the SWS_FILE_PDSSEND request type. We recommend that you use the SWS_FILE_SEND function for all PDS member or sequential dataset transmission requests. This request type supercedes and obsoletes the older SWS_FILE_PDSSEND request type. |
| SWS_FILE_QUEUE | This request type is used to cause small data members to be read into the
transaction's external data queue. Because the size of the external data queue is limited,
this function should not be used for members containing more than 2-300 logical records.
The logical record length is limited to 752 bytes in length and any excess bytes are
truncated without notification. Once read to the external data queue member data records can be retrieve using the SWSGetQueue HLL API interface. |
|
This request type is being retired, and should not be used for future Web
transaction HLL program development. Use the newer SWS_FILE_SEND request
type for future HLL program development, since it supercedes this PDS-only, DDNAME-only
API interface. The Shadow OS/390 Web Server will continue to support this request type so that HLL programs developed before SWS_FILE_SEND was available will continue to operate correctly without requiring a re-write. Future enhancements will only be made to the preferred SWS_FILE_SEND type. The SWS_FILE_PDSSEND request type is documented separately in the Deprecated High-Level Language SWSFILE (SWCPFI) Request Types page. |
SWCPFI Call Arguments
The SWSFILE (SWCPFI) function arguments are described in the table which follows. For send requests, each of the six arguments described must be present on the API CALL. Omit the sixth argument for queue operation requests.
| Arg. No. |
HLL Argument Type | I/O | Description of Argument | ||
|---|---|---|---|---|---|
| C | COBOL | PL/I | |||
| 1 | HDBC | USAGE POINTER |
PTR | Input | The Web Server connection handle. The connection handle is an opaque, four-byte address pointer. The connection handle is currently not used, and must be set to zero (NULL). |
| 2 | UDWORD | PIC S9(5) COMP |
FIXED BIN(31) |
Input | A four-byte flag-word indicating the request type of file-related operation to be
performed. One of the following values must be specified for this argument:
|
| 3 | UDWORD | PIC S9(5) COMP |
FIXED BIN(31) |
Input | A four-byte flag-word specifying various options for the API CALL request. The options
available for specification are defined as manifest constants within each HLL header file.
You combine the options which define your request by adding (or logically ORing) the manifest constants together to form a single, 32-bit flag word. The options are broken into three groups. One option constant may be selected from each of the groups shown below.
|
| 4 | UCHAR * | PIC X(8) or PIC X(44) |
CHAR(8) or CHAR(44) |
Input | This argument specifies either the DDNAME or the DSNAME of the file to be transmitted.
You must indicate which type of value is specified by coding one of the Name Specification
Options, given above.
For either DDNAME or DSNAME specifications, a null-terminated string may be specified, if desired. |
| 5 | UCHAR * | PIC X(8) | CHAR(8) | Input | When the file referenced by this call is a PDS or PDSE (BPAM) dataset, this argument must
contain the 8-byte, blank padded member name within the library which is to be
transmitted. A null-terminated string may be specified, if desired. For operations on other file types (non-BPAM), this is not examined by the API function. You should specify a NULL value of a type appropriate to the particular high-level language. |
| 6 | UCHAR * | PIC X(50) | CHAR(50) | Input | The 50-byte, blank-padded MIME content type value to be used when the data is
transmitted. A shorter string may be specified if the string is null terminated. Omit this argument for SWS_FILE_QUEUE requests. |
Return Values
SWSFILE always sets a signed numeric return code value. Possible values are:
- SWS_SUCCESS
- The operation succeeded. The specified operation was performed.
- SWS_NO_DATA_FOUND
- Indicates that the DDNAME, DSNAME or PDS member name is not valid because the dataset or member does not exist, or because the dataset is being held exclusively by some other address space.
- SWS_ERROR
- A parameter validation or run-time error was encountered. Error information is available using the SWSERROR function.
- SWS_ENVIRONMENT_ERROR
- The request can not be processed because of a run-time environmental error. For example, you invoked the API service outside of a Web transaction procedure or from outside the server's address space. Use the server's wrap-around trace to obtain diagnostic information.
- SWS_INVALID_HANDLE
- The connection handle argument is invalid. No error information can be returned using SWSERROR.
- Any other value
- The operation failed. Generally this indicates an unrecoverable loss of the communications session between the Shadow OS/390 Web Server and the client's Web browser program.
PL/I Example
DCL SCONN PTR; /* Connection Handle*/
DCL SDDNA CHAR(8) INIT('HTMFILE'); /* File DDNAME */
DCL SDSNA CHAR(44) INIT('MY.HTML.DATA'); /* File DSNAME */
DCL SDSNA2 CHAR(44) INIT('SOME.QSAM.DATA');/* File DSNAME */
DCL SMENA CHAR(8) INIT('HLLFILE'); /* Member name */
DCL SMENA2 CHAR(8) INIT('MYFILE'); /* Member name */
DCL SDUMMY FIXED BIN(31) INIT(0); /* NULL Argument */
DCL SCOTY CHAR(50) INIT('text/html'); /* Content type */
DCL SCOTY2 CHAR(50) INIT('image/gif'); /* Content type */
DCL SCOTY3 CHAR(50) INIT('text/plain');/* Content type */
DCL RC FIXED BIN(31); /* return code */
DCL DMHX FIXED BIN(31) BASED; /* Dummy Handle */
ADDR(SCONN)->DMHX = 0; /* Clear Connection Handle */
/* Send the member HLLFILE from the PDS allocated to the */
/* HTMFILE DD name using MIME type text/html. */
CALL SWSFILE( SCONN, /* Connection handle */
SWS_FILE_SEND, /* Send a file */
SWS_FILE_DDNAME + /* Arg 4 is a DD name */
SWS_SEND_TEXT, /* data is text format */
SDDNA, /* Send from this DDNAME */
SMENA, /* Send this member */
SCOTY ); /* File content */
RC = PLIRETV(); /* get return code */
IF RC ^= SWS_SUCCESS THEN /* exit program if bad RC */
EXIT;
/* Send binary data from the PDS 'MY.HTML.DATA(MYFILE) as */
/* MIME type image/gif. */
CALL SWSFILE( SCONN, /* Connection handle */
SWS_FILE_SEND, /* Send a file */
SWS_FILE_DSNAME + /* Arg 4 is a DSNAME */
SWS_FILE_BINARY, /* data in binary format */
SDSNA, /* Send from this DSNAME */
SMENA2, /* Send this member */
SCOTY2 ); /* File content */
RC = PLIRETV(); /* get return code */
IF RC ^= SWS_SUCCESS THEN /* exit program if bad RC */
EXIT;
/* Send the sequential file 'SOME.QSAM.DATA' as MIME type */
/* text/plain. */
CALL SWSFILE( SCONN, /* Connection handle */
SWS_FILE_SEND, /* Send a file */
SWS_FILE_DSNAME + /* Arg 4 is a DSNAME */
SWS_FILE_TEXT /* data in text format */
SDSNA2, /* Send from this DSNAME */
SDUMMY, /* NULL argument */
SCOTY3 ); /* File content */
RC = PLIRETV(); /* get return code */
IF RC ^= SWS_SUCCESS THEN /* exit program if bad RC */
EXIT;
C Example
HDBC sConn = NULL; /* Connection Handle */
long RC; /* return code */
/* Send the HLLFILE member from the PDS allocated with the */
/* DD name HTMFILE as MIME type text/html. */
rc = SWSFile( &sConn, /* Connection handle */
SWS_FILE_SEND, /* Send a file */
SWS_FILE_DDNAME | /* Arg 4 is a DD name */
SWS_SEND_TEXT, /* data is text format */
"HTMFILE", /* Send from this DDNAME */
"HLLFILE", /* Send this member */
"text/html" ); /* File content */
if (rc ^= SWS_SUCCESS) return; /* exit program if bad RC */
/* Send 'MY.HTML.DATA(MYFILE)' as MIME type image/gif */
rc = SWSFile( &sConn, /* Connection handle */
SWS_FILE_SEND, /* Send a file */
SWS_FILE_DSNAME | /* Arg 4 is a DSNAME */
SWS_SEND_BINARY, /* data is binary format */
"MY.HTML.DATA", /* Send from this DSNAME */
"MYFILE", /* Send this member */
"image/gif" ); /* File content */
if (rc ^= SWS_SUCCESS) return; /* exit program if bad RC */
/* Send 'SOME.QSAM.DATA' as MIME type text/plain. */
rc = SWSFile( &sConn, /* Connection handle */
SWS_FILE_SEND, /* Send a file */
SWS_FILE_DSNAME | /* Arg 4 is a DSNAME */
SWS_SEND_TEXT, /* data is binary format */
"SOME.QSAM.DATA", /* Send from this DSNAME */
"", /* NULL argument */
"text/plain" ); /* File content */
if (rc ^= SWS_SUCCESS) return; /* exit program if bad RC */
COBOL Example
77 SCONN USAGE IS POINTER.
77 SDDNA PIC X(8) VALUE 'HTMFILE'.
77 SDSNA PIC X(44) VALUE 'MY.HTML.DATA'.
77 SDSNA2 PIC X(44) VALUE 'SOME.QSAM.DATA'
77 SMENA PIC X(8) VALUE 'HLLFILE'.
77 SMENA2 PIC X(8) VALUE 'MYFILE'.
77 SCOTY PIC X(50) VALUE 'text/html'.
77 SCOTY2 PIC X(50) VALUE 'image/gif'.
77 SCOTY3 PIC X(50) VALUE 'text/plain'.
77 SDUMMY PIC S9(5) COMP VALUE 0.
77 SOPTION PIC S9(5) COMP.
* SEND THE HLLFILE MEMBER FROM THE PDS ALLOCATED TO
* THE HTMFILE DD NAME AS MIME TYPE text/html.
COMPUTE SOPTION = SWS-FILE-DDNAME + SWS-SEND-TEXT.
CALL 'SWCPFI' USING SCONN,
SWS-FILE-SEND,
SOPTION,
SDDNA,
SMENA,
SCOTY.
MOVE RETURN-CODE TO WS-SWSAPI-RETURN-CODE.
IF NOT SWS-SUCCESS GOBACK.
* SEND 'MY.HTML.DATA(MYFILE)' AS MIME TYPE image/gif.
COMPUTE SOPTION = SWS-FILE-DSNAME + SWS-SEND-BINARY.
CALL 'SWCPFI' USING SCONN,
SWS-FILE-SEND,
SOPTION,
SDSNA,
SMENA2,
SCOTY2.
MOVE RETURN-CODE TO WS-SWSAPI-RETURN-CODE.
IF NOT SWS-SUCCESS GOBACK.
* SEND 'SOME.QSAM.DATA AS MIME TYPE text/plain.
COMPUTE SOPTION = SWS-FILE-DSNAME + SWS-SEND-TEXT.
CALL 'SWCPFI' USING SCONN,
SWS-FILE-SEND,
SOPTION,
SDSNA2,
SDUMMY,
SCOTY3.
MOVE RETURN-CODE TO WS-SWSAPI-RETURN-CODE.
IF NOT SWS-SUCCESS GOBACK.