Previous Topic
Table Of Contents
Parent Topic
Next Topic

High-Level Language SWSGetQueue (SWCPQG) Function

Related Topics

Web Server API Function Index

	See PARSE PULL operation
	Not available from Other REXX Interpreters
	HLL entry point name is SWCPQG

SWSGetQueue is the Web Server API function used to read lines from the external data queue associated with the current Web transaction thread. The function returns the next (FIFO order) queued data line, if any, to a buffer in the application.

Normally, an external data queue is allocated and used only when executing Shadow/REXX procedures. However, a queue may now also be used from HLL programs. For HLL program executions, an external data queue may be pre-allocated by coding the QUEUESIZE( ) keyword. If one of the SWSxxxxxQueue HLL functions is invoked, an external data queue is created dynamically, using the default size, if one does not already exist.

CALL Arguments

The SWSGetQueue function takes four arguments, all of which are required.

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. 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	PTR	PIC X(nnn)	CHAR(nnn)	Output	This argument points to the data buffer which will be filled with the next queued line, if any. The queued line is truncated if longer than the size of this area. The area is binary-zero-padded on the right.
3	SDWORD	PIC S9(5) COMP	FIXED BIN(31)	Input	This argument gives the size of the data buffer pointed to by the 2nd argument.
4	SDWORD FAR *	PIC S9(5) COMP	FIXED BIN(31)	Input	This argument receives the actual queued data line size, regardless whether it was truncated during retrieval.

Return Values

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

SWS_SUCCESS: The operation succeeded.
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_SUCCESS_WITH_INFO: The queued line was longer than the data buffer provided and was truncated
SWS_NO_DATA_FOUND: No more lines are queued (queue is empty).
SWS_INVALID_HANDLE: The connection handle is invalid. No error information is available.
Any other value: The operation failed.

PL/I Example


 
    DCL  TCONN     PTR;                 /* Connection Handle       */
    DCL  RC        FIXED BIN(31);       /* return code             */
    DCL  DMHX      FIXED BIN(31) BASED; /* Dummy Handle field      */
    DCL  BUFFER    CHAR(752);           /* Buffer area             */
    DCL  BUFFLEN   FIXED BIN(31) INIT(752);  /* Size of buffer     */
    DCL  LINELEN   FIXED BIN(31) INIT(0);  /* Actual line size     */
 
    ADDR(TCONN)->DMHX = 0;              /* Clear Connection Handle */
 
    CALL SWSGetQueue( TCONN             /* read the queue          */
                      BUFFER,
                      BUFFLEN,
                      LINELEN );
 
    RC = PLIRETV();                     /* get return code         */
    IF RC = SWS_NO_DATA_FOUND THEN      /* queue is empty          */
       do something else
    IF RC ^= SWS_SUCCESS THEN           /* exit program if bad RC  */
       EXIT;

C Example


 
    HDBC    tConn     = NULL;           /* Connection Handle       */
    char    tbuffer[752];               /* buffer area             */
    SDWORD  tbufflen  = 752;            /* buffer length           */
    SDWORD  tLineLen  = 0;              /* actual line length      */
    long RC;                            /* return code             */
 
    rc = SWSGetQueue( &tConn,         /* query the queue        */
                      &tbuffer,
                      tbufflen,
                      &tLineLen );
 
    if (rc ^= SWS_SUCCESS) return;      /* exit program if bad RC  */

COBOL Example


 
    77  TCONN                USAGE IS POINTER.
    77  TBUFFER              PIC X(752).
    77  TBUFFLEN             PIC S9(5) COMP VALUE 752.
    77  TLINESIZE            PIC S9(5) COMP VALUE 0.
 
    CALL 'SWCPQG' USING TCONN,
                        TBUFFER,
                        TBUFFLEN,
                        TLINESIZE.
 
    MOVE RETURN-CODE TO WS-SWSAPI-RETURN-CODE.
    IF SWS-NO-DATA-FOUND THEN
       do something else
    END-IF.
    IF NOT SWS-SUCCESS GOBACK.

Top