SplEnumJob
This function lists the jobs in a print queue, optionally supplying status information on each job.
Syntax
SplEnumJob(pszComputerName, pszQueueName, ulLevel, pBuf, cbBuf, pcReturned, pcTotal, pcbNeeded, pReserved)
Parameters
- pszComputerName (PSZ) - input
- Name of computer where jobs are to be listed.
- A NULL string specifies the local workstation.
- pszQueueName (PSZ) - input
- Queue name.
- ulLevel (ULONG) - input
- Level of detail required.
- This must be 0 or 2.
- pBuf (PVOID) - output
- Buffer.
- The returned contents in the buffer depend on the value specified in ulLevel as follows:
- ulLevel Buffer Contents
- 0 An array containing a uJobId for each of pcReturned jobs.
- 2 An array containing a PRJINFO2 structure for each of pcReturned jobs.
- cbBuf (ULONG) - input
- Size, in bytes, of Buffer.
- It must be greater than 0.
- pcReturned (PULONG) - output
- Number of entries returned.
- pcTotal (PULONG) - output
- Number of entries available.
- pcbNeeded (PULONG) - output
- Size in bytes of available information.
- A value of 0 specifies that the size is not known.
- pReserved (PVOID) - output
- Reserved vaue, must be NULL.
Returns
- rc (SPLERR) - returns
- Return code.
- NO_ERROR (0)
- No errors occurred.
- ERROR_NOT_SUPPORTED (50)
- This request is not supported by the network.
- 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_QNotFound (2150)
- The printer queue does not exist.
- NERR_SpoolerNotLoaded (2161)
- The spooler is not running.
- NERR_InvalidComputer (2351)
- The computer name is invalid.
Sample
This sample code accepts a queue name from the command line, and then prints out all the information associated with each job in that queue. Level 0 and 2 are valid; we have chosen to print out level 2 information.
#define INCL_SPL
#define INCL_SPLDOSPRINT
#define INCL_SPLERRORS
#include <os2.h>
#include <stdio.h> /* for printf function */
INT main (argc, argv)
INT argc;
CHAR *argv[];
{
ULONG splerr ;
ULONG cbBuf ;
ULONG cTotal ;
ULONG cReturned ;
ULONG cbNeeded ;
ULONG ulLevel;
ULONG i ;
PSZ pszComputerName ;
PSZ pszQueueName ;
PVOID pBuf = NULL;
PPRJINFO2 pprj2 ;
/* Check that the command line entry was two parameters. */
if (argc != 2)
{
printf("Syntax: enumjob QueueName\n");
DosExit( EXIT_PROCESS , 0 ) ;
}
/* Either a NULL or a pointer to a NULL specify the local workstation. */
pszComputerName = (PSZ)NULL ;
/* Set queue name equal to the value entered at the command line. */
pszQueueName = argv[1];
/* Valid level are 0 and2. Level 2 gives info for a PRJINFO2 structure. */
ulLevel = 2L;
/* Make the call the first time with cbBuf = zero so that we can get a */
/* return of the number of bytes that are need for pBuf to hold all of */
/* the information. The bytes needed will be returned in cbNeeded. */
splerr = SplEnumJob(pszComputerName,pszQueueName, ulLevel, pBuf,0L,
&cReturned, &cTotal,
&cbNeeded, NULL) ;
/* Check that the return code is one of the two valid errors at this time. */
if (splerr == ERROR_MORE_DATA || splerr == NERR_BufTooSmall )
{
/* Allocate memory for pBuf. ( No error checking is done on DosAllocMem */
/* call to keep this sample code simple.) */
DosAllocMem( &pBuf, cbNeeded,
PAG_READ|PAG_WRITE|PAG_COMMIT );
/* Set bytes needed for buffer to the value returned by the first call. */
cbBuf = cbNeeded ;
/* Make the call with all the valid information. */
SplEnumJob(pszComputerName,pszQueueName, ulLevel,
pBuf, cbBuf, &cReturned,&cTotal,
&cbNeeded,NULL );
/* Set up a pointer to point to the beginning of the buffer in which we */
/* have the returned information */
pprj2=(PPRJINFO2)pBuf;
/* The number of structures in the buffer(pBuf) are returned in cReturned*/
/* Implement a for loop to print out the information for each structure. */
for (i=0; i<cReturned ;i++ )
{
printf("Job ID = %d\n", pprj2->uJobId);
printf("Job Priority = %d\n", pprj2->uPriority);
printf("User Name = %s\n", pprj2->pszUserName);
printf("Position = %d\n", pprj2->uPosition);
printf("Status = %d\n", pprj2->fsStatus);
printf("Submitted = %ld\n", pprj2->ulSubmitted);
printf("Size = %ld\n", pprj2->ulSize);
printf("Comment = %s\n", pprj2->pszComment);
printf("Document = %s\n\n",pprj2->pszDocument);
/* Increment the pointer to point to the next structure in the buffer*/
pprj2++;
} /* endfor */
/* Free the memory that we allocated to make the call. */
DosFreeMem(pBuf) ;
}
else
{
/* If any other error other than ERROR_MORE_DATA or NERR_BufTooSmall, then */
/* print the returned information. */
printf("SplEnumJob Error=%ld, Total Jobs=%ld, Returned Jobs=%ld, Bytes Needed=%ld\n",
splerr, cTotal, cReturned, cbNeeded) ;
}
DosExit( EXIT_PROCESS , 0 ) ;
return (splerr);
}
Call Sequence
#define INCL_SPL /* Or use INCL_PM, */
#include <os2.h>
PSZ pszComputerName; /* Name of computer where jobs are to be listed. */
PSZ pszQueueName; /* Queue name. */
ULONG ulLevel; /* Level of detail required. */
PVOID pBuf; /* Buffer. */
ULONG cbBuf; /* Size, in bytes, of Buffer. */
PULONG pcReturned; /* Number of entries returned. */
PULONG pcTotal; /* Number of entries available. */
PULONG pcbNeeded; /* Size in bytes of available information. */
PVOID pReserved; /* Reserved vaue, must be NULL. */
SPLERR rc; /* Return code. */
rc = SplEnumJob(pszComputerName, pszQueueName,
ulLevel, pBuf, cbBuf, pcReturned, pcTotal,
pcbNeeded, pReserved);