SplCreateDevice

This function establishes a print device on the local workstation or a remote server.

Syntax

SplCreateDevice(pszComputerName, ulLevel, pBuf, cbBuf)

Parameters

pszComputerName (PSZ) - input

Name of computer where print device is to be added.

A NULL string specifies the local workstation.

ulLevel (ULONG) - input

Level of detail provided.

This must be 3.

pBuf (PVOID) - input

Data structure.

It points to a PRDINFO3 data structure.

cbBuf (ULONG) - input

Size, in bytes, of data structure.

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_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_BufTooSmall (2123) : The API return buffer is too small.

NERR_DestExists (2153) : The print device already exists.

NERR_DestNoRoom (2157) : The maximum number of print devices has been reached.

NERR_DestInvalidState (2162) : This operation cannot be performed on the print device.

NERR_SpoolNoMemory (2165) : A spooler memory allocation failure occurred.

NERR_DriverNotFound (2166) : The device driver does not exist.

NERR_BadDev (2341) : The device is already in use as a communications device.

NERR_InvalidComputer (2351) : The computer name is invalid.

Sample

This sample code creates a PRDINFO3 structure with dummy parameters. This structure is then used to call SplCreateDevice to establish a print device on a local workstation.

#define INCL_BASE
#define INCL_DOSMEMMGR
#define INCL_SPL
#define INCL_SPLDOSPRINT

#include <os2.h>
#include <stdio.h>    /* for printf function */
#include <string.h>   /* for strcpy function */

INT main (argc, argv)
    INT argc;
    CHAR *argv[];
{
    ULONG  splerr  ;
    ULONG  cbBuf;
    ULONG  ulLevel ;
    PSZ    pszComputerName ;
    PSZ    pszPrintDeviceName ;
    PRDINFO3 prd3  ;

    if (argc != 2)
    {
       printf("Syntax:  sdcrt  DeviceName \n");
       DosExit( EXIT_PROCESS , 0 ) ;
    }
    /* We are going to create a print device on the local workstation. */
    pszComputerName = (PSZ)NULL ;

    /* Get the name from the command line.                             */
    pszPrintDeviceName = argv[1];

    /* Level 3 is valid. We will use level 3.                          */
    ulLevel = 3;

    /* Get size of buffer needed for a PRDINFO3 structure.             */
    cbBuf = sizeof(PRDINFO3);

    /* Set up the structure with dummy parameters.                     */
    prd3.pszPrinterName = pszPrintDeviceName;
    prd3.pszUserName = NULL;
    prd3.pszLogAddr = "LPT1";
    prd3.uJobId=0;
    prd3.pszComment= "Test comment";
    prd3.pszDrivers = "IBMNULL";
    prd3.usTimeOut = 777;

    /* Make the call. */
    splerr = SplCreateDevice(pszComputerName, ulLevel,
                             &prd3, cbBuf);

    /* Print out the results.                                                 */
    if (splerr == NO_ERROR)
       printf("The device was successfully created.");
    else
       printf("SplCreateDevice 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 print device is to be added. */
ULONG     ulLevel;          /*  Level of detail provided. */
PVOID     pBuf;             /*  Data structure. */
ULONG     cbBuf;            /*  Size, in bytes, of data structure. */
SPLERR    rc;               /*  Return code. */

rc = SplCreateDevice(pszComputerName, ulLevel,
       pBuf, cbBuf);

Remarks

The result of this function is the creation of a new print device definition.

The printer is set up to print on the logical address (port) defined by in PRDINFO3. If is NULL, the print device definition is created but is not connected to any logical address. In this case no printing can occur on that print device or from any print queue connected only to that print device. If a logical address is specified, it must already be defined in the PM_SPOOLER_PORTS section of the initialization file.

Note

To change the connection between a print device and a port, use SplSetDevice.

All device drivers and queues specified with the print device must already be defined to the spooler.

To add a remote print device requires administrator privilege.

Related Functions

• SplDeleteDevice
• SplEnumDevice
• SplEnumDriver
• SplEnumPort