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

Related Functions

• SplDeleteQueue
• SplEnumDevice
• SplEnumDriver
• SplEnumQueueProcessor