Previous Topic
Table Of Contents
Parent Topic
Next Topic

High-Level Language SWSSEND (SWCPSN) 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 SWCPSN

SWSSEND is the Web Server API function used to transmit outbound data to Web server clients, flush buffered data to the client, or to purge buffers which have not been transmitted.

CALL Arguments

The SWSSEND function takes four arguments. All four arguments must be specified on the call.

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 type of operation to be performed. One of the following manifest constants should be used to indicate the desired operation. The values are mutually exclusive; only one may be used.
SWS_SEND_BINARY
Indicates that the third argument contains binary-format data which should be transmitted to the Web client, as is.
SWS_SEND_TEXT
Indicates that the third argument contains text-format data which is processed by the Web server to remove trailing blanks, is translated from EBCDIC to ASCII, and a CR character appended to the end.
SWS_SEND_FLUSH
Indicates that all data currently held within outbound response buffers should committed for eventual transmission to the client. FLUSHed data cannot subsequently be PURGEd from the outbound response, and is always transmitted unless the communications session is lost. Transmission may occur immediately or may be deferred by the Server, under certain conditions, until the transaction ends.

We recommend that FLUSH requests not be used unless your application requires direct control over the outbound communications session, since it may interfere with Server-provided transaction recovery routines. If your application ABENDs following a FLUSH request, the Server's error recovery messages may be transmitted with invalid HTTP protocol response headers. The end user may not be properly informed that a processing error has occurred.

SWS_SEND_PURGE
Indicates that outbound data waiting for transmission in response buffers should be discarded without being transmitted to the client. PURGE operates only on outbound response data which has not been committed for transmission using the FLUSH request, and cannot be used to recall response data which was previously FLUSHed.
3 PTR PIC
X(nnn) 		CHAR(nnn) Input The buffer area containing the data to be transmitted to the Web client. The data value can be no longer than 8K in length. This argument must be specified, even if the second argument specifies a flush or purge operation. The length of the data value within the buffer area is specified by the forth argument.
4 SDWORD PIC
S9(5)
COMP 		FIXED
BIN(31) 		Input The size of the data value given by the third argument. This can be an integer fullword value in the range 0 to 8K. You can also use the manifest constant, SWS_NTS, to specify that data is a null-terminated string. This value should be zero for flush or purge operations.

Top

Return Values

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

SWS_SUCCESS
The operation succeeded. The output data has been buffered, or for flush and purge operations, the buffer operation has been completed.
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.
4
The operation failed due to loss of the communications session. Further outbound transmissions will not be possible.
8
The requested operation was invalid within the overall context of the transaction process. When this return code is set, the cause for the request rejection can normally be found in the wrap-around trace.
 
Possible reasons for return code 8 being set are:
  • An additional transmission buffer was needed, but could not be obtained. transmission of data cannot be performed in cross-memory mode.
  • An output request (TEXT or BINARY) is being made, but is invalid at the current time. This occurs if you attempt to transmit data after having issued an SWSFILE(SEND) request.

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

 

PL/I Example


 
    DCL  SCONN     PTR;                 /* Connection Handle       */
    DCL  SDATA     CHAR(256);           /* Text output area        */
    DCL  SSIZE     FIXED BIN(31);       /* Text length area        */
    DCL  RC        FIXED BIN(31);       /* return code             */
    DCL  DMHX      FIXED BIN(31) BASED; /* Dummy Handle field      */
 
    ADDR(SCONN)->DMHX = 0;              /* Clear Connection Handle */
 
    SDATA    = 'Hello World!';          /* Set output area         */
    SSIZE    = 12;                      /* set length              */
    CALL SWSSEND( SCONN                 /* send the text data      */
                  SWS_SEND_TEXT,
                  SDATA,
                  SSIZE );
    RC = PLIRETV();                     /* get return code         */
    IF RC ^= SWS_SUCCESS THEN           /* exit program if bad RC  */
       EXIT;

Top

C Example


 
    HDBC sConn   = NULL;                /* Connection Handle       */
    char sData[] = "Null-terminated!";  /* Text string definition  */
    long RC;                            /* return code             */
 
    rc = SWSSend( &sConn,               /* send the text data      */
                  SWS_SEND_TEXT,
                  sData,
                  SWS_NTS );
    if (rc ^= SWS_SUCCESS) return;      /* exit program if bad RC  */

 

COBOL Example


 
    77  SCONN                USAGE IS POINTER.
    77  SDATA                PIC X(80).
    77  SSIZE                PIC S9(5) COMP.
 
    MOVE 'HELLO WORLD!' TO SDATA.
    MOVE 12             TO SSIZE.
 
    CALL 'SWCPSN' USING SCONN,
                  SWS-SEND-TEXT,
                  SDATA,
                  SSIZE.
    MOVE RETURN-CODE TO WS-SWSAPI-RETURN-CODE.
    IF NOT SWS-SUCCESS GOBACK.

Top