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