SplQueryJob

This function retrieves information about a print job.

Syntax

SplQueryJob(pszComputerName, pszQueueName, ulJob, ulLevel, pBuf, cbBuf, pcbNeeded)

Parameters

pszComputerName (PSZ) - input

Name of computer where print job is to be queried.

A NULL string specifies the local workstation.

pszQueueName (PSZ) - input

Queue Name.

ulJob (ULONG) - input

Job identification number.

ulLevel (ULONG) - input

Level of detail required.

This must be 0, 2, or 3.

pBuf (PVOID) - in/out

Buffer.

The returned contents of the buffer depend on the value specify in ulLevel as follow:

ulLevel Buffer Contents

0 The job identifier

2 A PRJINFO2 structure, with variable information, up to the cbBuf of pBuf

3 A PRJINFO3 structure, with variable information, up to the cbBuf of pBuf.

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_JobNotFound (2151) :The print job does not exist.

NERR_SpoolerNotLoaded (2161) :The spooler is not running.

NERR_InvalidComputer (2351) :The computer name is invalid.

Sample

The following sample code will print out the information contained in a PRJINFO3 structure that is returned from a SplQueryJob call. The parameters that are entered on the command line are the computer name, queue name, and the job id.

#define INCL_SPL
#define INCL_SPLDOSPRINT
#define INCL_SPLERRORS
#include <os2.h>
#include <stdio.h>    /* for printf call  */
#include <stdlib.h>   /* for atoi call    */

INT main (argc, argv)
    INT argc;
    CHAR *argv[];
{
    INT       splerr;
    ULONG     cbBuf ;
    ULONG     cbNeeded ;
    ULONG     ulLevel ;
    ULONG     ulJob ;
    PSZ       pszComputerName ;
    PSZ       pszQueueName ;
    PVOID     pBuf;
    PPRJINFO3 pprj3 ;

    /* Input the parameters Computer Name, Queue Name,and Job ID. Check that  */
    /* three parameters have been entered along with the program name.        */
    if (argc != 4)
    {
       /* Print a message and exit if wrong number of parameters entered      */
       printf("Syntax:  sjqry  ComputerName  QueueName  JobID    \n");
       DosExit( EXIT_PROCESS , 0 ) ;
    }
    /* Set the parameters to the values entered on the command line.          */
    pszComputerName = argv[1] ;
    pszQueueName = argv[2] ;
    ulJob = atoi (argv[3]);

    /* Valid levels are 0,2,and 3. Level 3 returns a PRJINFO3 structure.      */
    ulLevel = 3 ;

    /* Call the function with cbBuf equal to zero in order to get the number  */
    /* of bytes needed returned in cbNeeded.                                  */
    splerr = SplQueryJob(pszComputerName,pszQueueName,ulJob,
                            ulLevel, (PVOID)NULL, 0L, &cbNeeded );

    /* Only continue if the error return code is one of the two following.    */
    if (splerr == NERR_BufTooSmall || splerr == ERROR_MORE_DATA )
    {
       /* Allocate memory for the buffer(pBuf). Only continue if memory is    */
       /* successfully allocated.                                             */
       if (DosAllocMem( &pBuf, cbNeeded,
                        PAG_READ|PAG_WRITE|PAG_COMMIT) )
       {
          /* Set the count of bytes needed for the buffer to the value        */
          /* returned in cbNeeded from the first call.                        */
          cbBuf = cbNeeded ;

          /* Make the call again with all the correct values.                 */
          SplQueryJob(pszComputerName,pszQueueName,ulJob,
                               ulLevel, pBuf, cbBuf, &cbNeeded) ;

          /* Set a pointer to point to the beginning of the buffer that holds */
          /* the returned structure.                                          */
          pprj3=(PPRJINFO3)pBuf;

          /* Print out the information for each element in the structure.     */
          printf("Job ID      = %d\n", pprj3->uJobId);
          printf("Job Priority= %d\n", pprj3->uPriority);
          printf("User Name   = %s\n", pprj3->pszUserName);
          printf("Position    = %d\n", pprj3->uPosition);
          printf("Status      = %d\n", pprj3->fsStatus);
          printf("Submitted   = %ld\n",pprj3->ulSubmitted);
          printf("Size        = %ld\n",pprj3->ulSize);
          printf("Comment     = %s\n", pprj3->pszComment);
          printf("Document    = %s\n", pprj3->pszDocument);
          printf("Notify Name = %s\n", pprj3->pszNotifyName);
          printf("Data Type   = %s\n", pprj3->pszDataType);
          printf("Parms       = %s\n", pprj3->pszParms);
          printf("Status      = %s\n", pprj3->pszStatus);
          printf("Queue       = %s\n", pprj3->pszQueue);
          printf("QProc Name  = %s\n", pprj3->pszQProcName);
          printf("QProc Parms = %s\n", pprj3->pszQProcParms);
          printf("Driver Name = %s\n", pprj3->pszDriverName);
          printf("Printer Name= %s\n", pprj3->pszPrinterName);

          /* If pDriverData is NULL, then we can not access any data.         */
          if (pprj3->pDriverData)
          {
             printf("  pDriverData->cb           - %ld\n",
                                    (ULONG)pprj3->pDriverData->cb);
             printf("  pDriverData->lVersion     - %ld\n",
                                    (ULONG)pprj3->pDriverData->lVersion) ;
             printf("  pDriverData->szDeviceName - %s\n",
                                       pprj3->pDriverData->szDeviceName) ;
          }
          printf("/n");

          /* Free memory that we allocated.                                   */
          DosFreeMem(pBuf) ;
       }
    }
    else
    {
       /* If we are here than we have an error code. Print it out.            */
       printf("SplQueryJob Error=%ld,Bytes Needed=%ld\n",splerr, 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 print job is to be queried. */
PSZ       pszQueueName;     /*  Queue Name. */
ULONG     ulJob;            /*  Job identification number. */
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 = SplQueryJob(pszComputerName, pszQueueName,
       ulJob, ulLevel, pBuf, cbBuf, pcbNeeded);

Related Functions

• SplEnumJob
• SplEnumQueue
• SplQueryQueue
• SplSetJob