SplEnumQueue
This function lists print queues on the local workstation or on a remote server, optionally supplying additional information.
Syntax
SplEnumQueue(pszComputerName, ulLevel,
pBuf, cbBuf, pcReturned, pcTotal, pcbNeeded,
pReserved);
Parameters
- pszComputerName (PSZ) - input
- Name of computer where queues are to be listed.
- A NULL string specifies the local workstation.
- ulLevel (ULONG) - input
- Level of detail.
- The level of detail required. This must be 3, 4, 5, 6 or 7.
- pBuf (PVOID) - output
- Buffer.
- The returned contents in the buffer depend on the value specified in ulLevel as follows:
ulLevel Buffer Contents
3 An array of PRQINFO3 structures. The fsType bit PRQ3_TYPE_APPDEFAULT is set for the application default queue only.
4 An array of *pcReturned PRQINFO3 structures in which each PRQINFO3 structure is followed by an array of PRJINFO2 structures, one for each job in the queue. cJobs in the PRQINFO3 structure gives the number of jobs in the array.
5 An array of PSZ, each pointing to a queue name.
6 An array of PRQINFO6 structures
7 An array of pcReturned PRQINFO3 structures in which each PRQINFO3 structure is followed by an array of PRJINFO4 structures, one for each job in the queue. cJobs in the PRQINFO3 structure gives the number of jobs in the array.
cbBuf (ULONG) - input Size, in bytes, of Buffer.
It must be greater than 0. Some systems do not allow a size greater than 65535.
- pcReturned (PULONG) - output
- Number of entries returned.
- pcTotal (PULONG) - output
- Total number of entries available.
- pcbNeeded (PULONG) - output
- Size in bytes of available information.
- A value of 0 specifies that the size is not known. This can occur when enumerating queues on a print server. To determine the buffer size needed, the caller should allocate a buffer in 4096-byte increments until a successful return code is received, or until the buffer size exceeds 65535.
- pReserved (PVOID) - output
- Reserved value, must be NULL.
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_InvalidComputer (2351)
- The computer name is invalid.
Sample
#define INCL_SPL /* Or use INCL_PM, */
#include <os2.h>
PSZ pszComputerName; /* Name of computer where queues are to be listed. */
ULONG ulLevel; /* Level of detail. */
PVOID pBuf; /* Buffer. */
ULONG cbBuf; /* Size, in bytes, of Buffer. */
PULONG pcReturned; /* Number of entries returned. */
PULONG pcTotal; /* Total number of entries available. */
PULONG pcbNeeded; /* Size in bytes of available information. */
PVOID pReserved; /* Reserved value, must be NULL. */
SPLERR rc; /* Return code. */
rc = SplEnumQueue(pszComputerName, ulLevel,
pBuf, cbBuf, pcReturned, pcTotal, pcbNeeded,
pReserved);
Remarks
This sample code enumerates all the queues and the jobs in them that are on the local workstation.
#define INCL_BASE
#define INCL_SPL
#define INCL_SPLDOSPRINT
#define INCL_SPLERRORS
#include <os2.h>
#include <stdio.h>
INT main ()
{
SPLERR splerr;
USHORT jobCount;
ULONG cbBuf;
ULONG cTotal;
ULONG cReturned;
ULONG cbNeeded;
ULONG ulLevel;
ULONG i,j;
PSZ pszComputerName;
PBYTE pBuf;
PPRQINFO3 prq;
PPRJINFO2 prj2;
ulLevel = 4L;
pszComputerName = (PSZ)NULL;
splerr = SplEnumQueue(pszComputerName,
ulLevel,
pBuf, 0L, /* cbBuf */
&cReturned,
&cTotal,
&cbNeeded,
NULL)
if (splerr == ERROR_MORE_DATA ||
splerr == NERR_BufTooSmall)
{
if (!DosAllocMem(&pBuf,
cbNeeded,
PAG_READ |
PAG_WRITE |
PAG_COMMIT))
{
cbBuf = cbNeeded;
splerr = SplEnumQueue(pszComputerName,
ulLevel,
pBuf,
cbBuf,
&cReturned,
&cTotal,
&cbNeeded, NULL)
if (splerr == NO_ERROR)
{
/* Set pointer to point to the beginning of the buffer */
prq = (PPRQINFO3)pBuf;
/* cReturned has the count of the number of PRQINFO3 structures */
for (i=0;i < cReturned; i++)
{
printf("Queue info: name - %s\n", prq->pszName);
if (prq->fsType & PRQ3_TYPE_APPDEFAULT)
printf(" This is the application default print queue\n");
printf(" priority - %d starttime - %d endtime - %d fsType - %X\n",
prq->uPriority,
prq->uStartTime,
prq->uUntilTime,
prq->fsType);
printf(" pszSepFile - %s\n", prq->pszSepFile);
printf(" pszPrProc - %s\n", prq->pszPrProc);
printf(" pszParms - %s\n", prq->pszParms);
printf(" pszComment - %s\n", prq->pszComment);
printf(" pszPrinters - %s\n", prq->pszPrinters);
printf(" pszDriverName- %s\n", prq->pszDriverName);
if (prq->pDriverData)
{
printf(" pDriverData->cb - %ld\n",
(ULONG)prq->pDriverData->cb);
printf(" pDriverData->lVersion - %ld\n",
(ULONG)prq->pDriverData->lVersion);
printf(" pDriverData->szDeviceName- %s\n",
prq->pDriverData->szDeviceName);
}
/* Save the count of jobs. There are this many PRJINFO2 */
/* structures following the PRQINFO3 structure */
jobCount = prq->cJobs;
printf("Job count in this queue is %d\n\n",jobCount);
/* Increment the pointer past the PRQINFO3 structure */
prq++;
/* Set a pointer to point to the first PRJINFO2 structure */
prj2=(PPRJINFO2)prq;
for (j=0;j < jobCount ; j++)
{
printf("Job ID = %d\n", prj2->uJobId);
printf("Job 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 jobCount */
/* After doing all the job structures, prj2 points to the next */
/* queue structure. Set the pointer for a PRQINFO3 structure */
prq = (PPRQINFO3)prj2;
}/*endfor cReturned */
}
DosFreeMem(pBuf);
}
} /* end if Q level given */
else
{
/* If we are here we had a bad error code. */
/* Print it and some other info. */
printf("SplEnumQueue Error=%ld,
Total=%ld,
Returned=%ld,
Needed=%ld\n",
splerr,
cTotal,
cReturned,
cbNeeded);
}
DosExit(EXIT_PROC