SplCreateQueue
This function creates a new print queue on the local workstation or on a remote server. A remote server setup requires the LAN Requester and Server software.
Syntax
SplCreateQueue(pszComputerName, ulLevel, pbBuf, cbBuf);
Parameters
- pszComputerName (PSZ) - input
- Name of computer where queue is to be created.
- A NULL string specifies a local workstation.
- ulLevel (ULONG) - input
- Level of detail provided.
- This must be 3 or 6.
- pbBuf (PVOID) - input
- Data structure.
- It points to a data structure depending on the value specified in ulLevel as follows:
- ulLevel Buffer Content.
- 3 a PRQINFO3 data structure
- 6 a PRQINFO6 data structure
- cbBuf (ULONG) - input
- Size, in bytes, of data structure.
- It must be greater than 0.
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_NAME (123)
- The computer name is invalid.
- ERROR_INVALID_LEVEL (124)
- The level parameter is invalid.
- NERR_NetNotStarted (2102)
- The network program is not started.
- NERR_RedirectedPath (2117)
- The operation is invalid on a redirected resource.
- NERR_BufTooSmall (2123)
- The API return buffer is too small.
- NERR_DestNotFound (2152)
- The printer destination cannot be found.
- NERR_QExists (2154)
- The printer queue already exists.
- NERR_DestInvalidState (2162)
- This operation cannot be performed on the print destination in its current state.
- NERR_SpoolNoMemory (2165)
- A spooler memory allocation failure occurred.
- NERR_DriverNotFound (2166)
- The device driver does not exist.
- NERR_DataTypeInvalid (2167)
- The data type is not supported by the queue processor.
- NERR_ProcNotFound (2168)
- The queue processor is not installed.
- NERR_BadDev (2341)
- The requested device is invalid.
- NERR_CommDevInUse (2343)
- This device is already in use as a communications device.
- NERR_InvalidComputer (2351)
- The computer name is invalid.
Sample
This sample code creates a queue on the local workstation. The queue is created with dummy parameters. The name is entered at the command line.
#define INCL_BASE
#define INCL_SPL
#define INCL_SPLDOSPRINT
#include <os2.h>
#include <stdio.h>
#include <string.h>
INT main (argc, argv )
INT argc;
CHAR *argv[];
{
ULONG splerr ;
ULONG cbBuf;
ULONG ulLevel ;
PSZ pszComputerName ;
PSZ pszQueueName ;
PRQINFO3 prq3 ;
if (argc != 2)
{
printf("Syntax: sqcrt QueueName \n");
DosExit( EXIT_PROCESS , 0 ) ;
}
pszComputerName = (PSZ)NULL ;
ulLevel = 3L;
/* Get the queue name from the argument entered at */
/* the command line. */
pszQueueName = argv[1];
/* Determine the size of the needed buffer. */
cbBuf = sizeof(PRQINFO3);
/* Set up the structure with some dummy parameters. */
prq3.pszName = pszQueueName;
prq3.uPriority=5;
prq3.uStartTime=0;
prq3.uUntilTime=0;
prq3.pszSepFile="c:\\os2\\sample.sep";
prq3.pszParms=NULL;
prq3.pszPrinters=NULL;
prq3.pszDriverName=NULL;
prq3.pDriverData="IBMNULL"; /* Set to Driver.Device name */
/* Make the call with the proper parameters. */
splerr = SplCreateQueue(pszComputerName, ulLevel,
&prq3, cbBuf);
/* Print out the error return code and some other information. */
printf("SplCreateQueue Error=%ld, cbNeeded=%ld\n",
splerr, cbBuf) ;
DosExit( EXIT_PROCESS , 0 ) ;
return (splerr);
}
Call Sequence
#define INCL_SPL /* Or use INCL_PM, */ #include <os2.h> PSZ pszComputerName; /* Name of computer where queue is to be created. */ ULONG ulLevel; /* Level of detail provided. */ PVOID pbBuf; /* Data structure. */ ULONG cbBuf; /* Size, in bytes, of data structure. */ SPLERR rc; /* Return code. */ rc = SplCreateQueue(pszComputerName, ulLevel, pbBuf, cbBuf);
Remarks
To create a queue on a remote server requires administrator privilege. The following fields are required in PRQINFO3 or PRQINFO6:
- uPriority
- uStartTime
- uUntilTime
- pszSepFile
- pszParms
If a queue of the name specified in pszName already exists on pszComputerName, the call fails unless the queue is marked for deletion. In this case, the queue is not deleted, and the creation fields are used to perform a SplSetQueue function on the queue.
If pszPrinters is NULL, the queue is created but not connected to any printer.
pszDriverName can be a NULL string, in which case pDriverData. is ignored. Otherwise, pszDriverName must refer to the name of a device driver that is already defined in the initialization file (for example, "IBM4019").