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

Related Functions

• SplCopyJob
• SplDeleteJob
• SplQueryJob