View source for SplQueryQueue

This function supplies information about a print queue, and, optionally, about the jobs in it.

== Syntax ==
  SplQueryQueue(pszComputerName, pszQueueName,
       ulLevel, pBuf, cbBuf, pcbNeeded);
== Parameters ==
;pszComputerName (PSZ) - input:Name of computer where queue is to be queried.
:A NULL string specifies the local workstation.
;pszQueueName (PSZ) - input:Queue name.
;ulLevel (ULONG) - input:Level of detail required.
:This must be 3, 4, 5, 6 or 7.
;pBuf (PVOID) - in/out:Buffer.
:The returned contents of the buffer depend on the value specified in ulLevel as follows:

ulLevel Buffer Contents 

3 A PRQINFO3 structure, with associated variable information up to cbBuf. The fsType bit PRQ3_TYPE_APPDEFAULT is set for the application default queue only. 

4 A PRQINFO3 structure, with associated variable information, and an array of PRJINFO2 structures, one for each job in the queue, up to cbBuf. 

5 A queue name of type PSZ. 

6 A PRQINFO6 structure, with associated variable information up to cbBuf. 

7 A PRQINFO3 structure, with associated variable information, and an array of PRJINFO4 structures, one for each job in the queue, up to cbBuf. 

;cbBuf (ULONG) - input: Size, in bytes, of Buffer.
:It must be greater than 0.
;pcbNeeded (PULONG) - output:Size in bytes of available information.

== Returns ==
;rc (SPLERR) - returns : Return code.
*NO_ERROR (0) :No errors occurred.
*ERROR_ACCESS_DENIED (5) :Access is denied.
*ERROR_NOT_SUPPORTED (50) :This request is not supported by the network.
*ERROR_BAD_NETPATH (53) :The network path cannot be located.
*ERROR_INVALID_PARAMETER (87) :An invalid parameter is specified.
*ERROR_INVALID_LEVEL (124) :The level parameter is invalid.
*ERROR_MORE_DATA (234) :Additional data is available.
*NERR_NetNotStarted (2102) :The network program is not started.
*NERR_BufTooSmall (2123) :The API return buffer is too small.
*NERR_QNotFound (2150) :The printer queue does not exist.
*NERR_InvalidComputer (2351) :The computer name is invalid.

== Remarks ==
If ulLevel is 3 or 4, and pBuf cannot hold the entire PRQINFO3 structure, SplQueryQueue returns NERR_BufTooSmall (2123).

If ulLevel is 6, and pBuf cannot hold the entire PRQINFO6 structure, SplQueryQueue returns NERR_BufTooSmall (2123).

If ulLevel is 4, and pBuf cannot hold all the available PRJINFO2 structures, SplQueryQueue returns ERROR_MORE_DATA (234).

To obtain the size of buffer required, call SplQueryQueue with the required value of ulLevel, cbBuf set to 0 (zero), and a NULL buffer. The number of bytes required is returned in pcbNeeded.

== Sample ==
This sample code queries the local workstation for a queue name that is entered at the command prompt. The query is done at level 4 which returns returns in the buffer information in a PRQINFO3 structure and follows this with PRJINFO2 structures - one for each job in the queue.
<pre>
#define INCL_SPL
#define INCL_SPLDOSPRINT
#define INCL_SPLERRORS

#include <os2.h>
#include <stdio.h>

INT main (argc, argv)
INT argc;
CHAR *argv[];

{
  ULONG  splerr;
  ULONG  cbBuf;
  ULONG  cbNeeded;
  ULONG  ulLevel;
  ULONG  i;
  USHORT uJobCount;
  PSZ    pszComputerName;
  PSZ    pszQueueName;
  PVOID  pBuf;
  PPRJINFO2 prj2;
  PPRQINFO3 prq3 ;

  if (argc != 2)
  {
    printf("Syntax:  setqryq  QueueName \n");
    DosExit(EXIT_PROCESS, 0);
  }

  pszComputerName = (PSZ)NULL;
  pszQueueName = argv[1];
  ulLevel = 4L;
  splerr = SplQueryQueue(pszComputerName,
                         pszQueueName,
                         ulLevel,
                         (PVOID)NULL,
                         0L,
                         &cbNeeded);

  if (splerr != NERR_BufTooSmall ||
      splerr != ERROR_MORE_DATA)
  {
    printf("SplQueryQueue Error=%ld, cbNeeded=%ld\n",splerr, cbNeeded);
    DosExit(EXIT_PROCESS, 0);
  }

  if (!DosAllocMem(&pBuf, cbNeeded,
                   PAG_READ  |
                   PAG_WRITE |
                   PAG_COMMIT))
  {
    cbBuf = cbNeeded;
    splerr = SplQueryQueue(pszComputerName,
                           pszQueueName,
                           ulLevel,
                           pBuf,
                           cbBuf,
                           &cbNeeded);
    prq3=(PPRQINFO3)pBuf;
    printf("Queue info: name- %s\n", prq3->pszName);
    if (prq3->fsType & PRQ3_TYPE_APPDEFAULT)
       printf(" This is the application default print queue\n");
       printf("  priority - %d  starttime - %d  endtime - %d fsType - %X\n",
                 prq3->uPriority,
                 prq3->uStartTime,
                 prq3->uUntilTime,
                 prq3->fsType);
       printf("  pszSepFile    - %s\n", prq3->pszSepFile);
       printf("  pszPrProc     - %s\n", prq3->pszPrProc);
       printf("  pszParms      - %s\n", prq3->pszParms);
       printf("  pszComment    - %s\n", prq3->pszComment);
       printf("  pszPrinters   - %s\n", prq3->pszPrinters);
       printf("  pszDriverName - %s\n", prq3->pszDriverName);

    if (prq3->pDriverData)
    {
      printf("  pDriverData->cb           - %ld\n",
                (ULONG)prq3->pDriverData->cb);
      printf("  pDriverData->lVersion     - %ld\n",
                (ULONG)prq3->pDriverData->lVersion);
      printf("  pDriverData->szDeviceName - %s\n",
                prq3->pDriverData->szDeviceName);
    }
    /* Store the job count for use later in the for loop */
    uJobCount = prq3->cJobs;
    printf("Job count in this queue is %d\n\n",uJobCount);

    /* Increment the pointer to the PRQINFO3 structure       */
    /* so that it points to the first structure after itself */
    prq3++;

    /* Cast the prq3 pointer to point to a PRJINFO2 structure, */
    /* and set a pointer to point to that place                */
    prj2=(PPRJINFO2)prq3;
    for (i=0 ; i<uJobCount ;i++)
    {
      printf("Job ID    = %d\n",  prj2->uJobId);
      printf("Priority  = %d\n",  prj2->uPriority);
      printf("User Name = %s\n",  prj2->pszUserName);
      printf("Position  = %d\n",  prj2->uPosition);
      printf("Status    = %d\n",  prj2->fsStatus);
      printf("Submitted = %ld\n", prj2->ulSubmitted);
      printf("Size      = %ld\n", prj2->ulSize);
      printf("Comment   = %s\n",  prj2->pszComment);
      printf("Document  = %s\n\n",prj2->pszDocument);

      /* Increment the pointer to point to the next structure */
      prj2++;
    } /* endfor */
    DosFreeMem(pBuf);
  }
  DosExit(EXIT_PROCESS, 0);
  return (splerr);
}
</pre>

== Related Functions ==
*[[SplEnumQueue]]
*SplQueryJob
*SplSetJob
*SplSetQueue

[[Category:Spl]]