SplQueryQueue: Difference between revisions
Created page with "This function supplies information about a print queue, and, optionally, about the jobs in it. == Syntax == SplQueryQueue(pszComputerName, pszQueueName, ulLevel, p..." |
mNo edit summary |
||
Line 1: | Line 1: | ||
This function supplies information about a print queue, and, optionally, about the jobs in it. | This function supplies information about a print queue, and, optionally, about the jobs in it. | ||
== Syntax == | == Syntax == | ||
SplQueryQueue(pszComputerName, pszQueueName, | SplQueryQueue(pszComputerName, pszQueueName, | ||
ulLevel, pBuf, cbBuf, pcbNeeded); | ulLevel, pBuf, cbBuf, pcbNeeded); | ||
== Parameters == | == Parameters == | ||
;pszComputerName (PSZ) - input | ;pszComputerName (PSZ) - input:Name of computer where queue is to be queried. | ||
:Name of computer where queue is to be queried. | :A NULL string specifies the local workstation. | ||
;pszQueueName (PSZ) - input:Queue name. | |||
:A NULL string specifies the local workstation. | ;ulLevel (ULONG) - input:Level of detail required. | ||
:This must be 3, 4, 5, 6 or 7. | |||
;pszQueueName (PSZ) - input | ;pBuf (PVOID) - in/out:Buffer. | ||
:Queue name. | :The returned contents of the buffer depend on the value specified in ulLevel as follows: | ||
;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 | ulLevel Buffer Contents | ||
Line 35: | Line 25: | ||
7 A PRQINFO3 structure, with associated variable information, and an array of PRJINFO4 structures, one for each job in the queue, 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 | ;cbBuf (ULONG) - input: Size, in bytes, of Buffer. | ||
: Size, in bytes, of Buffer. | :It must be greater than 0. | ||
;pcbNeeded (PULONG) - output:Size in bytes of available information. | |||
: It must be greater than 0. | |||
;pcbNeeded (PULONG) - output | |||
:Size in bytes of available information. | |||
== Returns == | == Returns == | ||
;rc (SPLERR) - returns : Return code. | ;rc (SPLERR) - returns : Return code. | ||
*NO_ERROR (0) :No errors occurred. | |||
*NO_ERROR (0) | *ERROR_ACCESS_DENIED (5) :Access is denied. | ||
:No errors occurred. | *ERROR_NOT_SUPPORTED (50) :This request is not supported by the network. | ||
*ERROR_ACCESS_DENIED (5) | *ERROR_BAD_NETPATH (53) :The network path cannot be located. | ||
:Access is denied. | *ERROR_INVALID_PARAMETER (87) :An invalid parameter is specified. | ||
*ERROR_NOT_SUPPORTED (50) | *ERROR_INVALID_LEVEL (124) :The level parameter is invalid. | ||
:This request is not supported by the network. | *ERROR_MORE_DATA (234) :Additional data is available. | ||
*ERROR_BAD_NETPATH (53) | *NERR_NetNotStarted (2102) :The network program is not started. | ||
:The network path cannot be located. | *NERR_BufTooSmall (2123) :The API return buffer is too small. | ||
*ERROR_INVALID_PARAMETER (87) | *NERR_QNotFound (2150) :The printer queue does not exist. | ||
:An invalid parameter is specified. | *NERR_InvalidComputer (2351) :The computer name is invalid. | ||
*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 == | == Remarks == | ||
If ulLevel is 3 or 4, and pBuf cannot hold the entire PRQINFO3 structure, SplQueryQueue returns NERR_BufTooSmall (2123). | |||
If ulLevel is | If ulLevel is 6, and pBuf cannot hold the entire PRQINFO6 structure, SplQueryQueue returns NERR_BufTooSmall (2123). | ||
If ulLevel is | 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. | |||
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> | <pre> | ||
#define INCL_SPL | #define INCL_SPL | ||
Line 215: | Line 171: | ||
} | } | ||
</pre> | </pre> | ||
== Related Functions == | == Related Functions == | ||
* [[ | * [[SplEnumQueue]] | ||
* [[SplQueryJob]] | * [[SplQueryJob]] | ||
* [[SplSetJob]] | * [[SplSetJob]] | ||
* [[SplSetQueue]] | * [[SplSetQueue]] | ||
[[Category:Spl]] | [[Category:Spl]] |
Revision as of 19:32, 12 December 2019
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.
#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); }