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.

Sample

#define INCL_SPL /* Or use INCL_PM, */
#include <os2.h>

PSZ       pszComputerName;  /*  Name of computer where queue is to be queried. */
PSZ       pszQueueName;     /*  Queue name. */
ULONG     ulLevel;          /*  Level of detail required. */
PVOID     pBuf;             /*  Buffer. */
ULONG     cbBuf;            /*  Size, in bytes, of Buffer. */
PULONG    pcbNeeded;        /*  Size in bytes of available information. */
SPLERR    rc;               /*  Return code. */

rc = SplQueryQueue(pszComputerName, pszQueueName,
       ulLevel, pBuf, cbBuf, pcbNeeded);

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.

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.

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

Related Functions

• plEnumQueue
• SplQueryJob
• SplSetJob
• SplSetQueue