Jump to content

SplQueryQueue: Difference between revisions

From EDM2
Created page with "This function supplies information about a print queue, and, optionally, about the jobs in it. == Syntax == SplQueryQueue(pszComputerName, pszQueueName, ulLevel, p..."
 
Ak120 (talk | contribs)
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.  
 
== Sample ==
<pre>
#define INCL_SPL /* Or use INCL_PM, */
#include <os2.h>
 
PSZ      pszComputerName;  /*  Name of computer where queue is to be queried. */
PSZ      pszQueueName;    /*  Queue name. */
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 = SplQueryQueue(pszComputerName, pszQueueName,
      ulLevel, pBuf, cbBuf, pcbNeeded);
 
</pre>


== Remarks ==
== Remarks ==
If ulLevel is 3 or 4, and pBuf cannot hold the entire PRQINFO3 structure, SplQueryQueue returns NERR_BufTooSmall (2123).


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


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.


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 ==
* [[plEnumQueue]]
* [[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);
}

Related Functions