Previous Topic Table Of Contents Parent Topic Next Topic |  | # High-Level Language SWSFILE (SWCPFI) Function Related Topics Web Server API Function Index
| 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.
SWS_FILE_PDSSEND | 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: SWS_FILE_SEND This request type is used to request outbound transmission of PDS members or an entire sequential datasets. This request type should be used for all future HLL development. SWS_FILE_QUEUE This request type is used to request that the file data records be read into the transactions external data queue. SWS_FILE_PDSSEND This operation type has been superceded by the SWS_FILE_SEND request type, which should be used for all future HLL program development. This request type continues to be supported and is documented separately.
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. Name Specification Options One option from this group must be coded. This option indicates whether the call refers to the MVS file using a DD name or fully-qualified dataset name. SWS_FILE_DDNAME The fourth argument for this call to SWSFILE (SWCPFI) specifies the DDNAME of the MVS dataset. SWS_FILE_DSNAME The fourth argument for this call to SWSFILE (SWCPFI) specifies a fully-qualified MVS dataset name. Data Contents Format Options One option from this group must be coded. This option specifies the format of the data contained within the dataset; either text or binary. The Server transmits binary format data with no modifications, but applies various translation and editing options to text format data before transmission. SWS_SEND_TEXT The file contains text format data. Before outbound transmission, the Server translates the information from EBCDIC to ASCII, strips trailing blanks, and appends a carriage return character to each line. If the file contains HTML Extension Statements the Server will process these to tailor the final output, unless extension processing is surpressed by the SWS_FILE_NOHTX option. SWS_SEND_BINARY The file contains binary format data. The Server transmits the data, as is, without modification. HTML Extension Processing Options One option from this group may optionally be coded, but none are required. No option from this group should be coded when SWS_FILE_BINARY has been specified. This option controls how, or if, HTML Extension Statements within a text format file are processed by the Server before transmission. SWS_FILE_HTX The Server will process HTML Extension Statements. This option is the default for all text format files, so it need not be explicitly coded except for documentation purposes. SWS_FILE_NOHTX HTML Extension Statement processing will be surpressed. SWS_FILE_HTXREXXRULES Indicates that the Server will replace uninitialized variables located during HTML Extension processing with the upper-case variable name. If this option is not specified, the Server replaces uninitialized variables with a NULL string.
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. When the SWS_FILE_DDNAME option is used, this value must be the 8-byte, blank padded DDNAME for the file. When the SWS_FILE_DSNAME option is used, this value must be the 44-byte, blank padded dataset name for the file. 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.

Top

## 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;

Top

## 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  */

Top

## 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.

Top