KC_SPOOLOUT - Establish connections to printers

Using KC_SPOOLOUT you can establish connections to printers. You can:

• establish connections to all printers for which there are print jobs in the associated message queue and to which no connection yet exists.

• establish a connection to the printers which are assigned to a certain LTERM partner. The name of the LTERM partner must be passed in the identification area.

Execution / transaction management / cluster

The KC_SPOOLOUT call is not subject to transaction management. It cannot be rolled back by an RSET call.

Connection setup is triggered by the call, i.e. a job is merely initiated; this fact, however, gives no information as to whether and when a connection will actually be established. You can subsequently ascertain the existence of the connection with an information query (e.g. KC_GET_OBJECT with obj_type=KC_LTERM).

The following applies in UTM cluster applications (Unix, Linux and Windows systems):
The call applies locally to the node, i.e. the connections to the printers are only established in the node application at which the call is issued.

Duration of a connection

Connections to printers for which no print level (PLEV) has been defined remain in existence until they are shut down explicitly (see KC_MODIFY_OBJECT) or the application run is terminated. Connections to printers for which a print level has been defined
(PLEV > 0) are shut down after printing.

Using KDCAPPL SPOOLOUT=ON ("KDCAPPL - Change properties and limit values for an operation") you can establish connections to all printers for which print jobs exist.

Data to be supplied

Function of the call	Data to be entered in the
	parameter area 1	identification area	selection area	data area
Establish a connection to a printer or to the printers of a printer pool	obj_number: 1	Name of the LTERM partner assigned to the printer or printer pool	——	——
Establish connections to all currently unconnected printers for which there are print jobs	obj_number: 0	——	——	——

¹ The operation code KC_SPOOLOUT must always be stated in the parameter area.

Parameter settings
Parameter area
Field name	Content
version	KC_ADMI_VERSION_1
retcode	KC_RC_NIL
version_data	KC_VERSION_DATA_11
opcode	KC_SPOOLOUT
obj_number	1 / 0
id_lth	Length of object name in identification area / 0
select_lth	0
data_lth	0
Identification area
Object name / —
Selection area
—
Data area
—

KDCADMI call

KDCADMI (&parameter_area, &identification_area, NULL, NULL) or
KDCADMI (&parameter_area, NULL, NULL, NULL)

Data returned by UTM
Parameter area
Field name	Content
retcode	Return codes

obj_number

The values specified in obj_number have the following meanings:

• obj_number = 0:
  UTM is to establish a connection to all printers to which connection currently exists and for which there are print jobs.

• obj_number = 1:
  UTM is to establish a connection to the printer or printer pool assigned to a certain LTERM partner. You must pass the name of the LTERM partner in the identification area.

id_lth

You must specify in id_lth the length of the object name which you are passing to UTM in the identification area.

• for obj_number = 0 you should specify id_lth = 0.

• for obj_number = 1 you should specify in id_lth the length of the name which is passed in the identification area.

Identification area

The information you must specify in the identification area is determined by obj_number:

• obj_number = 0:
  You may not specify any object name in the identification area. In the KDCADMI call you must pass the null pointer.

• obj_number = 1:
  In the identification area, pass the name of the LTERM partner assigned to the printer or printer pool. To do this, assign the union kc_id_area through the identification area and pass the name of the LTERM partner in the kc_name8 field.

retcode

UTM writes the return codes for the call to the retcode field. In addition to the return codes listed in section "Return codes", the following codes may also occur:

Main code = KC_MC_REJECTED

The call was rejected by UTM.

Subcodes:

KC_SC_NOT_EXISTENT

The LTERM partner specified in the identification area does not exist.

KC_SC_NOT_ALLOWED

The operation is not allowed for the stated LTERM partner.
Possible reasons are:

• the LTERM partner is a dialog partner, i.e. it is not defined for printers (usage_type != 'O')

• no printer/printer pool is currently assigned to the LTERM partner

• the LTERM partner or the associated printer is currently disabled

• the printer belonging to the LTERM partner has been deleted from the configuration

• there are no messages for the specified printer, i.e. the LTERM partner’s message queue is empty.

KC_SC_DELETED

The specified LTERM partner has been deleted from the configuration.