Previous Topic
Table Of Contents
Parent Topic
Next Topic

High-Level Language SWSRESP (SWCPRE) 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 SWCPRE

SWSRESP (entry point "SWCPRE") is a high level function used to buffer customized outbound HTTP response headers for subsequent transmission to Web client browsers.

SWSRESP may be used to buffer an HTTP response header at any time during the life of a Web transaction. Using SWSRESP to buffer HTTP response headers differs from merely writing these headers using SWSSEND:

When using SWSSEND, HTTP headers must be written before any message body data (e.g. an HTML page or binary GIF image) has been output.
However, SWSRESP may be used before, during or after output of the message body.

The Server merges the HTTP response headers which have been buffered using SWSRESP with any other data generated by the Web transaction. This merge processing takes place when the Web transaction ends and causes the complete output stream to be assembled and transmitted to the client.

SWSRESP is only valid when a Web transaction procedure is operating in server-parsed header mode since the merging/assembly, described above, is disabled in non-parsed-header mode. A call to SWSRESP will return an error if the Web transaction is not operating in server-parsed header mode.

CALL Arguments

The SWSRESP (entry point "SWCPRE") function takes five arguments. All five arguments must be specified on the call.

Arg No.	HLL Argument Type			I/O	Description of Argument
Arg No.	C	COBOL	PL/I	I/O	Description of Argument
1	HDBC	Usage Pointer	PTR	Input	The Web Server connection handle. This 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 type of operation to be performed. The only value currently supported is: `SWS_RESPONSE_ADD`
3	PTR	PIC X(nnn)	CHAR(nnn)	Input	The buffer area containing the header to be transmitted to the Web client. The data value can be no longer than 8K in length. The length of the header is specified by the 4^th argument. The colon after the response/general header is added by the SWSRESP function; therefore it is not* necessary to include it in the third argument of the SWSRESP call.*
4	SDWORD	PIC S9(5) COMP	FIXED BIN(31)	Input	The length of the data value given by the third argument. This can be an integer fullword value in the range of 0 to 8K. You can also use the manifest constant `SWS_NTS` to specify that the data is a null terminated string.
4	PTR	PIC X(nnn)	CHAR(nnn)	Input	The buffer area containing the entity body text to be transmitted to the Web client. The data value can be no longer than 8K in length. The length of the entity body text is specified by the 5^th argument.
5	SDWORD	PIC S9(5) COMP	FIXED BIN(31)	Input	The length of the data value given by the fourth argument. This can be an integer fullword value in the range of 0 to 8K. You can also use the manifest constant `SWS_NTS` to specify that the data is a null terminated string.

Top

Return Values

SWSRESP always sets a signed numeric return code value. Possible values are:

SWS_SUCCESS: The operation succeeded. The specified header has been placed in the output buffer.
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 has failed.

The SWSRESP operation is not logged to the Server's wrap-around trace file unless an error occurs. If you need to trace information sent using SWSRESP, use the SENDTRACE keyword of the /*WWW rule header.

PL/I Example


 
    DCL   SCONN     PTR;              /* Connection Handle      */
    DCL   HDATA     CHAR(256);        /* Header area            */
    DCL   HSIZE     FIXED BIN(31);    /* Header length          */
    DCL   BDATA     CHAR(256);        /* Body area              */
    DCL   BSIZE     FIXED BIN(31);    /* Body length            */
    DCL   DMHX      FIXED BIN(31) BASED;  /* Dummy Handle field */
    ADDR(SCONN)->DMHX=0;           /* Zero connection handle */
    HDATA="Pragma";                   /* Set header data        */
    HSIZE=6;                          /* Set header length      */
    BDATA="no-cache";                 /* Set body data          */
    BSIZE=8;                          /* Set body length        */
    CALL SWSRESP(SCONN                /* Send the response      */
             SWS_RESPONSE_ADD,
             HDATA,
             HSIZE,
             BDATA,
             BSIZE);
    RC=PLIRETV();                     /* Get return code        */
    IF RC ^=SWS_SUCCESS THEN          /* exit if bad RC         */
             EXIT;

Top

C Example


 
    HDBC   sConn     = NULL;        /* Connection Handle */
    char   hData[]   = "Pragma";    /* Header text       */
    char   bData[]   = "no-cache";  /* body text         */
    long   RC;                      /* return code       */
    rc = SWSResp(&sConn,            /* send the response */
          SWS_RESPONSE_ADD,
          hData,
          SWS_NTS,
          bData,
          SWS_NTS);
    If(rc ^=SWS_SUCCESS) return;    /* exit if bad rc    */

COBOL Example


 
    77 SCONN         USAGE IS POINTER.
    77 HDATA         PIC X(80).
    77 HSIZE         PIC S9(5) COMP.
    77 BDATA         PIC X(80).
    77 BSIZE         PIC S9(5) COMP.
    MOVE 'Pragma'    TO HDATA.
    MOVE 6           TO HSIZE.
    MOVE 'no-cache'  TO BDATA.
    MOVE 8           TO BSIZE.
    CALL 'SWCPRE' USING SCONN,
             SWS-RESPONSE-ADD,
             HDATA,
             HSIZE,
             BDATA,
             BSIZE.
    MOVE RETURN CODE TO WS-SWSAPI-RETURN-CODE.
    IF NOT SWS-SUCCESS GOBACK.

Top